Gandi

Gandi

.NET REST client for the Gandi v5 API

This library allows you to create, read, update, and delete LiveDNS DNS 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.

• Prerequisites
• Installation
• Configuration
• Usage
  • LiveDNS
    • Find DNS records
    • Get a DNS record
    • Create or update a DNS record
    • Delete a record
• Examples
  • Dynamic DNS updates
  • ACME verification

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

• Get a Gandi API authentication token. This token can be either an API Key or Personal Access Token.
  • 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.
  • You can always create a Personal Access Token.
    • Go to either User Settings or Organizations › ⚙ Manage.
    • Click Create a token.
    • If prompted, choose the organization which owns the domain whose DNS records you want to manage, then click Next.
    • Choose a name and expiration period for the token.
    • Choose whether the token will be allowed to access all domains in the organization, or just a subset of them.
    • Allow permission to "Manage domain name technical configurations."
    • Click Create.
    • Copy the token text. Keep it somewhere safe, because Gandi won't show it to you again.
    • 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.
    • Click Done.
  • If you need to change the auth token of an existing GandiClient instance, for example if the old token expires and a new one is written to a configuration file that reloads on changes, you can set the IGandiClient.AuthToken property any time during the lifetime of the instance.
• Construct a new instance of GandiClient, passing the Personal Access Token or API Key to the constructor.

  using Gandi;
  
  using IGandiClient gandi = new GandiClient("<personal access token or API key>");
  

Advanced configuration

• You can access the HttpClient instance 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, you can pass it to the GandiClient(HttpClient?) constructor. Make sure the HttpClient's HttpMessageHandler inherits from IUnfuckedHttpHandler (one easy way to do this is for HttpClient to be an UnfuckedHttpClient) so that client request authentication filters and JSON serialization work correctly. To wrap your own HttpMessageHandler instance (such as a customized SocketsHttpHandler or DelegatingHandler), pass it to the UnfuckedHttpHandler(HttpMessageHandler?) constructor.

Usage

LiveDNS

Get a LiveDNS API client for your second-level/registered domain name using IGandiClient.LiveDns(string). This object has async methods on it that perform HTTP calls to Gandi's LiveDNS API.

ILiveDns liveDns = gandi.LiveDns("mydomain.com");

Find DNS records

Return a list of all DNS records in the domain, optionally filtered by name or type (A, CNAME, etc). If no results are found, returns an empty enumeration.

ILiveDns liveDns = gandi.LiveDns("mydomain.com");
IEnumerable<DnsRecord> allRecords = await liveDns.List();
IEnumerable<DnsRecord> cnames     = await liveDns.List(type: RecordType.CNAME);
IEnumerable<DnsRecord> www        = await liveDns.List(name: "www");

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). To specify a record at the root/origin of your domain, pass @ as the name. The time to live is optional, defaults to 3 hours if you set it to null, and is clipped to the allowed range [5 minutes, 30 days]. You must supply at least one value for the record.

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, records of all 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");

Examples

Dynamic DNS updates

using IGandiClient gandi = new GandiClient(personalAccessToken);

await gandi.LiveDns("aldaviva.com").Set(new DnsRecord(RecordType.A, "west", DnsRecord.MinTimeToLive, "172.11.57.29"));

ACME verification

using IGandiClient gandi = new GandiClient(personalAccessToken);
ILiveDns liveDns = gandi.LiveDns("aldaviva.com");

// Generate a new ACME order, authorization, and DNS challenge

DnsRecord txtRecord = new(RecordType.TXT, "_acme-challenge.west", DnsRecord.MinTimeToLive, dnsChallengeValue);
await liveDns.Set(txtRecord);

// Repeatedly ask certificate authority to validate the challenge until its status is valid

await liveDns.Delete(txtRecord);

// Generate a private key and certificate signing request, then request a certificate chain from the CA