Gandi 0.0.0-alpha3

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.

1. Prerequisites
2. Installation
3. Configuration
4. Usage
   • LiveDNS
     1. Find DNS records
     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, and pass it to the AuthToken property of GandiClient. 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.
     • Pass the API Key to the AuthToken property of your GandiClient instance.

     gandi.AuthToken = "<your API key>";
     

   • You can always 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.
     11. Pass the Personal Access Token to the AuthToken property of your GandiClient instance.

     gandi.AuthToken = "<your personal access token>";
     

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 authentication client request filters work.

Usage

LiveDNS

Find DNS records

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