Aller au contenu Aller au menu principal Aller au menu secondaire Aller au pied de page

The .fr API for Registrars (1/4)

Home > Observatory and resources > Expert papers > The .fr API for Registrars (1/4)
10/24/2022

Since 1 October 2022, the .fr Registrars have had an API (Application Programming Interface) with which to automate their operations1. It complements the use of EPP (Extensible Provisioning Protocol) for those who find EPP too complex, or who simply wish to carry out certain actions that EPP does not allow. In this series of articles, we will explain the API and its advantages and give specific examples of its use.

Note that access to the API is not public, but reserved to Afnic-accredited Registrars. Members of the public wishing to interrogate the content of the .fr domain automatically can use the RDAP (Registration Data Access Protocol)2.

What is an API?

The abbreviation API (Application Programming Interface) refers to two different things. Traditionally it designates the interface of a software library, the signature of the functions that the programmer will use, and which hopefully will remain fairly stable in general so as not to have to change the code too often. For example, the documentation of the standard Python library tells us that the str.upper function takes as its parameters only the object (a string of characters) to which it is applied, and that it will return a string of characters (in upper case). The set of types, constants, functions, etc. defined in this documentation constitutes the API of the standard Python language library.

But nowadays, API refers more often than not to something else – an interface accessed via the internet, generally by means of requests using the HTTP protocol. It is still a tool for programmers (the ‘P’ in API) but instead of executing local code it calls  code running on a remote computer. There are now innumerable online services using such APIs. Most of the time these APIs follow the REST (REpresentational State Transfer) principles: a URI (Uniform Resource Identifier) to designate an object to which an action is to be applied, and the use of HTTP methods (GET, PATCH, DELETE, etc.) and HTTP response status codes (such as the famous 404) to indicate, respectively, the action to be taken and its result. When more information needs to be transmitted, this is now generally encoded in JSON (JavaScript Object Notation).

Uses

As we have seen, APIs are made for programmers. The aim is to automate tasks rather than having a human clicking on the fields of a web form. If you have few and infrequent operations, automation will no doubt not be very useful. APIs are designed to handle large volumes of operations, or operations that are repeated often.

An obvious example of their use, for a Registrar, may be to add functions to its website3, for example to determine whether or not a domain name is available. Thanks to the API4, the Registrar can add to the code of its website requests to the registry’s servers, which will respond stating whether or not the name can be registered.

But the API can also be used to carry out operations en masse. If you manage only thirty domain names, adding an additional name server to these thirty domains via a web form would be laborious (not to mention the risks of human error when inputting the information). The API simplifies all this, a simple loop on the list of names and you’re done. The same applies for example for creating names. If you have a list of twenty names to create, with the same information, using the API to create them is simpler and safer than entering the twenty names one by one5.

For some of these operations, one could use EPP, certainly, but programmers often find it complex and many prefer an API REST, with the classic HTTP and JSON.

The .fr API and its documentation

Let’s take a look now at the API of the .fr TLD. Its complete documentation is accessible online. The principle is that you are going to have to make HTTP requests to URIs starting with https://api-sandbox.nic.fr/v1/ for the sandbox6 and with https://api.nic.fr/v1/ for the actual database. The parameters will be indicated in the URI if the object already exists  or in the JSON data sent with the HTTP request. The responses will contain the HTTP response status code and possibly data in JSON format. The documentation indicates the parameters, the content of the responses, and gives examples using cURL command lines, which is very practical for trying out the API. Here for example is how to enquire about the availability of a domain:

curl --header ‘Content-Type: application/json’ \

    --header "Authorization: Bearer eyJhbGnQ0…" \

    --data '{"names": ["doesnotexist.fr", "nic.fr"]}' \

  https://api-sandbox.nic.fr/v1/domains/check | \

 jq .

In detail: we indicate to cURL two fields of the HTTP header, one giving the type of data sent (JSON) and the other providing authentication (covered in greater detail in the following section). The data sent are an object in JSON format containing two domain names, the availability or otherwise of which we wish to know. The result of the cURL command is passed to the jq (JSON query language) program, which will format the JSON in more readable form:

{

  "response": [

    {

      "name": "doesnotexist.fr",

      "available": true

    },

    {

      "name": "nic.fr",

      "available": false,

      "reason": "IN_USE"

    }

  ]

}

We see that one of the two names is available for registration, the other having already been reserved.

cURL was used only for the example and for debugging; you will probably use the programming language of your choice (which is one of the main advantages of network APIs). We will look at this in subsequent articles.

Authentication

We’ve seen above that access to the API is not public. We must therefore deal with the question of authentication. To carry out operations with the API, you must first obtain a token, which is done by applying to the URI https://login-sandbox.nic.fr/auth/realms/fr/protocol/openid-connect/token (for the sandbox) or  https://login.nic.fr/auth/realms/fr/protocol/openid-connect/token (for production). You will need to indicate your identifier and your password. The token is valid for a limited time. It will then have to be placed in the field of the HTTP Authorization heading. The following examples of code show specifically how to do this.

The code

So let’s look at the code. The articles that follow will show the programs for the following operations:

  • obtaining a list of one’s domains7,
  • enquiring about the availability of a domain and whether it can be registered,
  • creating a domain,
  • deleting a domain,
  • adding a name server to all one’s domains.

Three programming languages will be used: Python, Go and Elixir8. For reasons of space, the articles will show only a simplified version of the programs. A complete version is available on our Gitlab.


1 – It is also available for the French Overseas domains such as .pm.

2 – This will be the subject of a forthcoming article!

3 – I remind you however that certain operations carried out via the API may be sensitive, for example deleting a domain name, and that developing a secured website, one that does not allow an ill-intentioned third party to carry out operations, is a delicate task. So think about security and do not improvise as a developer without knowing the best practices of secure development.

4 – For enquiring about availability as in the example, one cannot use the DNS, since a name may be registered without being delegated in the DNS. The RDAP is not ideal either, as it provides both too much information (detailed information on a domain) and not enough (it indicates only whether a name has been registered, not whether it is registrable, (not reserved for example)).

5 -But be careful: automation can have adverse consequences if there’s a bug in the program. While certain operations such as enquiring about availability are relatively harmless, those that alter the database of the .fr domain are more sensitive. An example might be a clumsy loop that creates large quantities of names for which you would be invoiced. A loop deleting or altering domain names might be another. So don’t hesitate to use the sandbox (as in the following examples of code) to test.

6 – Test environment, which does not use real data and is not invoiced.

7 – This is an example of an operation that cannot be done with EPP.

8 -There is also a version in Rust in the repository but this is not covered by an article.