Gandi 0.0.0-alpha2

Gandi

.NET REST client for the Gandi v5 API

This library allows you to create, read, update, and delete LiveDNS records in your Gandi domains.

It's similar to G6.GandiLiveDns, but it's compatible with both Personal Access Token and API Key authentication, public types have interfaces so you can mock and actually test your dependent code, and it's compatible with a wider variety of runtimes.

1. Prerequisites
2. Installation
3. Configuration
4. Usage
   • LiveDNS
     1. Find DNS records in domain
     2. Get a DNS record
     3. Create or update a DNS record
     4. Delete a record

Prerequisites

• .NET runtime compatible with .NET Standard 2.0
  • .NET 5 or later
  • .NET Core 2 or later
  • .NET Framework 4.6.2 or later
• Gandi domain name
  • ✅ Domain must be using LiveDNS, the default for new domains (ns-*-*.gandi.net)
  • ❌ Classic DNS (*.dns.gandi.net) is incompatible; you will need to migrate to LiveDNS
  • ❌ External nameservers (with glue records) are incompatible; you will need to update the record on the external nameserver instead of on Gandi's nameservers

Installation

This library is available in the Gandi package on NuGet Gallery.

dotnet add package Gandi

Configuration

1. Construct a new instance of GandiClient.

   using Gandi;
   
   using var gandi = new GandiClient();
   

2. Get a Gandi authentication token to pass to this client.
   • If you already have a Gandi API Key, you can use it to authenticate this client to your Gandi account.
     • If your Gandi account doesn't already have an API Key, it's too late, you can't make one anymore.
     • If you don't remember your API Key, you can regenerate it using Account › Authentication options › Developer access › API key.
     • Pass the API Key to the ApiKey property of your GandiClient instance.

     gandi.ApiKey = apiKey;
     

   • If you don't already have an API key, you can create a Personal Access Token.
     1. Go to either User Settings or Organizations › ⚙ Manage.
     2. Click Create a token.
     3. If prompted, choose the organization which owns the domain whose DNS records you want to manage, then click Next.
     4. Choose a name and expiration period for the token.
     5. Choose whether the token will be allowed to access all domains in the organization, or just a subset of them.
     6. Allow permission to "Manage domain name technical configurations."
     7. Click Create.
     8. Copy the token text. Keep it somewhere safe, because Gandi won't show it to you again.
     9. Set a calendar reminder to notify you before this token expires. There is no way for Gandi to notify you or for clients to refresh or renew tokens, so you will have to repeat all of these steps when your token eventually expires.
     10. Click Done.

Advanced configuration

• You can access the HttpClient and HttpMessageHandler instances used by GandiClient if you want to configure timeouts, extra request headers, or add requests or response filters.
• If you want to provide your own HttpClient and HttpMessageHandler instances, you can subclass GandiClient and call its protected constructor GandiClient(UnfuckedHttpHandler, UnfuckedHttpClient), which take wrappers around HttpMessageHandler and HttpClient to provide filtering, serialization, and builders.

Usage

LiveDNS

Find DNS records in domain

Return a list of all DNS records in the domain, optionally filtered by name or type (A, CNAME, etc).

var liveDns = gandi.LiveDns("mydomain.com");
IEnumerable<DnsRecord> allRecords = await liveDns.List();
IEnumerable<DnsRecord> cnames = await liveDns.List(RecordType.CNAME);

Get a DNS record

Return one DNS record in the domain with the given name and type, or null if it was not found.

DnsRecord? wwwRecord = await liveDns.Get(RecordType.A, "www");

Create or update a DNS record

Set a DNS record's value, automatically creating it if it didn't already exist, or modifying it if it already existed (upserting).

await liveDns.Set(new DnsRecord(RecordType.A, "www", TimeToLive.FromHours(1), "1.2.3.4"));

Delete a record

Remove a record with the given name and optionally the given type. If the type is not specified, all record types with the given name are deleted. This method returns successfully even if the record did not exist, because either way it doesn't exist after the method completes, so it's in the desired state.

await liveDns.Delete(RecordTytpe.CNAME, "www");