How to use DNS API with Insomnia (REST Client)

Introduction

If you like to automate things in your domain registration process, an API comes in very handy. Luckily, Hetzner provides a DNS service, which allows you to use their nameservers (NS) as primary NS or as secondary NS.

In this tutorial, I'll show you how to set up and use a REST Client (like Insomnia or Postman) to connect to the Hetzner DNS API.

Note: I use Insomnia on Linux, but it should look pretty similar if you are on MAC or Windows.

When I mention "API docs" in this tutorial, I am referring to this one: https://dns.hetzner.com/api-docs

Prerequisites

You need:

• An up and running Insomnia application at your desktop
  

(see their official "Install Insomnia" guide).

• Access to your Hetzner account (to create an API token)
• Internet connection

Step 1 - Create an API token

Login to your Hetzner account at: https://accounts.hetzner.com/login

On the upper right, click on the app switcher icon and select DNS. Or open the DNS Console directly at: https://dns.hetzner.com/

• In the DNS Console on the upper right, click on the user icon and select the menu item API tokens:

  

• Choose a distinctive name for the token and create it:

  

  After you've pressed the button, you'll see a popup window that contains your access token.

• Copy and save the token

  Make sure to save it to a save place. It won't be shown again.

  

Step 2 - Setup Insomnia

Open your Insomnia application and create a new Request Collection:

Now we add a new Environment in Insomnia:

You can use the Base Environment (click on it), and enter 2 variables we will use later on:

Step 3 - Create API requests

Based on the API documentation, you can now go on and create requests.

Step 3.1 - Find requirements for the API request

API documentation: https://dns.hetzner.com/api-docs#operation/GetZones

Based on the following image, we can analyze how our request is built:

1. We choose the kind of request in the sidebar navigation
2. Here, we see which query parameters are possible, and what values are required
3. The API token is required for any request. But depending on the kind of request, other parameters might also be needed!
4. The URL to send the request to
5. The Request samples section shows how a request should look like

Step 3.2 - Create the request in Insomnia

Create a new request:

1. Double-click on the placeholder "New Request" and give it a name (e.g. Get all Zones)
2. In the address bar of Insomnia, make sure you select GET. Then start to type _. and wait 3 seconds... Insomnia now opens a pulldown with all variables you have set before in the environment. Here we choose _.url and complete the path with the information we got from the API docs before.

As you might remember, there was a required field for this request... the "Auth-API-Token". It needs to be sent in the Header of the request.

1. Click on the tab "Auth" below the address bar and select "API Key"
2. Enter the key
3. For value, you go again with _. and wait three seconds... Then, choose the variable: _.token.
4. Make sure ADD TO is set to Header (which is default)
5. Send request and look for the response.

Should look similar to the following image:

Step 3.3 - Additional parameters

We've seen before in the API documentation, that requests can have multiple parameters. So here is how we add those parameters to our request:

1. Go to the tab "Query"
2. Enter the name of the key and the value (I used key: search_name with value config)

Regarding the API documentation, search_name shows me up to 100 zones that contain the search word.

Step 4 - Create all requests you need

The above steps work in same way for all other available API requests that Hetzner provides for its DNS. You can easily create as many requests as needed in Insomnia.

HINT: Generally, if you request data from the API, the action to use is GET. But if you send data to the API it is POST. Make sure, you choose equal action in your insomnia-request-address bar.

Step 4.1 - Import the Cloud API

If an API has an API specification (declaration) - like OpenApi, WSDL, etc. - it's possible to import all declared API requests at once with Insomnia. Unfortunately, Hetzner didn't provide a declaration for its DNS API yet, so we hope it will be available soon.

BUT: Hetzner provides an unofficial OpenApi declaration for their "Cloud API". You'll find it at: https://docs.hetzner.cloud/spec.json

Here is how you can import it to Insomnia:

1. Open Menu > Application > Preferences > Data (tab) > Import Data > From URL

   

2. Enter the URL: https://docs.hetzner.cloud/spec.json and submit it.

3. You get a notice that lists everything that was imported:

   

Conclusion

You activated your API access at your Hetzner account and learned how to read the API documentation of Hetzner to create your own API requests in a REST Client like Insomnia.

License: MIT