Using Zonemaster-Backend JSON-RPC API

Table of contents

Introduction

This is a guide for getting started with the Zonemaster JSON-RPC API service (running as a daemon).

Note that this guide makes a number of assumptions about your setup:

  • That it is a Unix-like environment.
  • That you have Zonemaster-Backend installed according to the installation guide
  • That Zonemaster-Backend is running. See installation guide for how to start Zonemaster-Backend.
  • If you have changed IP address (default 127.0.0.1) or port (default 5000) then you must specify that in the commands below. Here we assume default.

For this guide we will use the two Zonemaster-Backend tools zmb and zmtest. Both are installed when Zonemaster-Backend is installed. To get more information what parameters they expect, run zmb -h and zmtest -h.

With zmtest you can start a domain test and get the result directly. With zmb you can also do that, but in several steps, but on the other hand, zmb offers many more possibilities. Actually, zmtest uses zmb behind the scen.

The zmb tool uses the JSON-RPC API to interact with Zonemaster-Backend. Zonemaster-GUI also uses the same JSON-RPC API to start tests and fetch the test results.

Check that the JSON-RPC API service is running and answering properly

zmb version_info

To get a more readable output, pipe the command through jq:

zmb version_info | jq

If there is no response from the JSON-RPC API service, go to the installation guide for how to start or restart it.

Below most commands will be piped through jq, but for processing you might want to have the JSON on one line, or you might want to look at the options for jq to extract fields (see jq -h).

Run a test of the zonemaster.net zone using zmtest

To just run a test zmtest is the simple tool to use:

zmtest zonemaster.net

The tool will also display the result, which will be a large JSON object (here truncated).

testid: 879d13569db70fde
100% done
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "created_at": "2024-10-25T09:28:38Z",
    "hash_id": "879d13569db70fde",
    "params": {
      "domain": "zonemaster.net",
      "ds_info": [],
      "ipv4": true,
      "ipv6": true,
      "nameservers": [],
      "priority": 10,
      "profile": "default",
      "queue": 0
    },
    "results": [
      {
        "level": "INFO",
        "message": "Using version v6.0.0 of the Zonemaster engine.\n",
        "module": "System",
        "testcase": "Unspecified"
      },
      {
        "level": "INFO",
        "message": "The parent zone is \"net\" as returned from name servers \"a.gtld-servers.net/192.5.6.30; a.gtld-servers.net/2001:503:a83e::2:30; b.gtld-servers.net/192.33.14.30; b.gtld-servers.net/2001:503:231d::2:30; c.gtld-servers.net/192.26.92.30; c.gtld-servers.net/2001:503:83eb::30; d.gtld-servers.net/192.31.80.30; d.gtld-servers.net/2001:500:856e::30; e.gtld-servers.net/192.12.94.30; e.gtld-servers.net/2001:502:1ca1::30; f.gtld-servers.net/192.35.51.30; f.gtld-servers.net/2001:503:d414::30; g.gtld-servers.net/192.42.93.30; g.gtld-servers.net/2001:503:eea3::30; h.gtld-servers.net/192.54.112.30; h.gtld-servers.net/2001:502:8cc::30; i.gtld-servers.net/192.43.172.30; i.gtld-servers.net/2001:503:39c1::30; j.gtld-servers.net/192.48.79.30; j.gtld-servers.net/2001:502:7094::30; k.gtld-servers.net/192.52.178.30; k.gtld-servers.net/2001:503:d2d::30; l.gtld-servers.net/192.41.162.30; l.gtld-servers.net/2001:500:d937::30; m.gtld-servers.net/192.55.83.30; m.gtld-servers.net/2001:501:b1f9::30\".\n",
        "module": "Basic",
        "testcase": "Basic01"
      },
      {
        "level": "INFO",
        "message": "The zone \"zonemaster.net\" is found.\n",
        "module": "Basic",
        "testcase": "Basic01"
      },
      {
        "level": "INFO",
        "message": "Authoritative answer on SOA query for \"zonemaster.net\" is returned by name servers \"ns2.nic.fr/192.93.0.4; ns2.nic.fr/2001:660:3005:1::1:2; nsa.dnsnode.net/194.58.192.46; nsa.dnsnode.net/2a01:3f1:46::53; nsp.dnsnode.net/194.58.198.32; nsp.dnsnode.net/2a01:3f1:3032::53; nsu.dnsnode.net/185.42.137.98; nsu.dnsnode.net/2a01:3f0:400::32\".\n",
        "module": "Basic",
        "testcase": "Basic02"
      },
(...)

You will find the meaning of all fields in the outputs in Zonemaster-Backend JSON-RPC API reference.

Run a test of the zonemaster.net zone using zmb

If we instead use zmb then this will be done in three steps (that happen behind the scen when using zmtest):

  1. Enqueue test.
  2. Check if testing has completed (progress) - maybe several times.
  3. Fetch result (maybe several times with different translations).

Enqueue a test

To enqueue a test of zonemaster.net we run zmb start_domain_test --domain zonemaster.net | jq and immediately get the response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "879d13569db70fde"
}

The results field holds the test ID which we need for further steps. It always consists of 16 hexadecimal digits.

Check the progress

To check the progress we run zmb test_progress --test-id 879d13569db70fde | jq with the test ID from enqueueing, and get the response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 8
}

Now the results field holds the progress of testing, an integer between 0 and 100 to mean 0% to 100%. 0% means that testing has not started (maybe many tests in the queue) and 100% means that testing has completed.

We have to stay in the check step until the test has reached 100%. In our example above, it is 8%, so we run the command again and now we get the response

{
  "result": 100,
  "jsonrpc": "2.0",
  "id": 1
}

Fetch the results

When the test has completed the test results can be fetched. The test ID is found above and then the language has to be chosen. Here en is used. More about languages below. Run zmb get_test_results --test-id 879d13569db70fde --lang en | jq and get a JSON structure with data (as with zmtest). Again, the JSON structure is long and is truncated here.

{
  "id": 1,
  "result": {
    "results": [
      {
        "message": "Using version v6.0.0 of the Zonemaster engine.\n",
        "testcase": "Unspecified",
        "level": "INFO",
        "module": "System"
      },
      {
        "module": "Basic",
        "level": "INFO",
        "testcase": "Basic01",
        "message": "The parent zone is \"net\" as returned from name servers \"a.gtld-servers.net/192.5.6.30; a.gtld-servers.net/2001:503:a83e::2:30; b.gtld-servers.net/192.33.14.30; b.gtld-servers.net/2001:503:231d::2:30; c.gtld-servers.net/192.26.92.30; c.gtld-servers.net/2001:503:83eb::30; d.gtld-servers.net/192.31.80.30; d.gtld-servers.net/2001:500:856e::30; e.gtld-servers.net/192.12.94.30; e.gtld-servers.net/2001:502:1ca1::30; f.gtld-servers.net/192.35.51.30; f.gtld-servers.net/2001:503:d414::30; g.gtld-servers.net/192.42.93.30; g.gtld-servers.net/2001:503:eea3::30; h.gtld-servers.net/192.54.112.30; h.gtld-servers.net/2001:502:8cc::30; i.gtld-servers.net/192.43.172.30; i.gtld-servers.net/2001:503:39c1::30; j.gtld-servers.net/192.48.79.30; j.gtld-servers.net/2001:502:7094::30; k.gtld-servers.net/192.52.178.30; k.gtld-servers.net/2001:503:d2d::30; l.gtld-servers.net/192.41.162.30; l.gtld-servers.net/2001:500:d937::30; m.gtld-servers.net/192.55.83.30; m.gtld-servers.net/2001:501:b1f9::30\".\n"
      },
      {
        "message": "The zone \"zonemaster.net\" is found.\n",
        "module": "Basic",
        "testcase": "Basic01",
        "level": "INFO"
      },
      {
        "level": "INFO",
        "testcase": "Basic02",
        "module": "Basic",
        "message": "Authoritative answer on SOA query for \"zonemaster.net\" is returned by name servers \"ns2.nic.fr/192.93.0.4; ns2.nic.fr/2001:660:3005:1::1:2; nsa.dnsnode.net/194.58.192.46; nsa.dnsnode.net/2a01:3f1:46::53; nsp.dnsnode.net/194.58.198.32; nsp.dnsnode.net/2a01:3f1:3032::53; nsu.dnsnode.net/185.42.137.98; nsu.dnsnode.net/2a01:3f0:400::32\".\n"
      },
(...)

Find available languages

The result can be presented in several languages, depending on installation. To find out what languages that are available, run zmb get_language_tags | jq.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "da",
    "en",
    "es",
    "fi",
    "fr",
    "nb",
    "sv"
  ]
}

Find previous tests

It is possible to find previous tests of a specific domain (zone). Run zmb get_test_history --domain zonemaster.net |jq to get all tests of zonemaster.net. The output looks like the following:

{
  "jsonrpc": "2.0",
  "result": [
    {
      "undelegated": false,
      "created_at": "2024-10-25T09:54:38Z",
      "id": "00669309ac7887c3",
      "overall_result": "ok"
    },
    {
      "overall_result": "ok",
      "id": "879d13569db70fde",
      "undelegated": false,
      "created_at": "2024-10-25T09:28:38Z"
    }
  ],
  "id": 1
}

Now you can get the results of any of the listed tests by running get_test_results with selected test ID and language as above.

Other APIs

There are a few other APIs that can be used throught zmb, and can be found by zmb -h and in Zonemaster-Backend JSON-RPC API reference. The APIs for batch testing are covered in Using Zonemaster Backend for batch testing.

IDN domain names

When enqueuing a test of an IDN domain name with zmb start_domain_test it is possible to provide the domain name as either A-label or U-label. E.g. both "räksmörgås.se" or "xn--rksmrgs-5wao1o.se" (the same domain name) work as well.

The same is also true if using Curl instead (see below).

Using Curl instead

Instead of using zmb it is possible to run the commands by curl, which requires that the JSON structure is created, but can give greater flexibility. The method can also be copied into different programming languages when scripting.

The same enqueuing of the zonemaster.net zone as above will then be:

curl -sS -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "id": 2, "method": "start_domain_test", "params": {"domain": "zonemaster.net"}}' http://localhost:5000/ | jq .

And fetching the result, when completed, will be:

curl -sS -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "id": 5, "method": "get_test_results", "params": {"id": "879d13569db70fde", "language": "en"}}' http://localhost:5000/ | jq .

The format of the JSON structure for every method is found in the Zonemaster-Backend JSON-RPC API reference.