Data format¶

The API accepts and emits JSON. The Accept: header determines the output format. An unknown value or */* will cause a 400 Bad Request.

All text is UTF-8 and HTTP headers will reflect this.

Data types:

empty fields: null but present
Regex: implementation defined
Dates: ISO 8601

General Collections Interface¶

Collections generally support GET and POST with these meanings:

GET¶

Retrieve a list of all entries.

The special type and url fields are included in the response objects:

type: name of the resource type
url: url to the object

Response format:

[
  obj1
  [, further objs]
]

Example:

[
  {
    "type": "AType",
    "id": "anid",
    "url": "/atype/anid",
    "a_field": "a_value"
  },
  {
    "type": "AType",
    "id": "anotherid",
    "url": "/atype/anotherid",
    "a_field": "another_value"
  }
]

POST¶

Create a new entry. The client has to supply the entry in the request body, in JSON format. application/x-www-form-urlencoded data MUST NOT be sent.

Clients SHOULD not send the ‘url’ field.

Client body:

obj1

Example:

{
  "type": "AType",
  "id": "anewid",
  "a_field": "anew_value"
}

REST¶

GET: List/Retrieve. Success reply: 200 OK
POST: Create. Success reply: 201 Created, with new object as body.
PUT: Update. Success reply: 200 OK, with modified object as body. For some operations, 204 No Content is returned instead (and the modified object is not given in the body).
DELETE: Delete. Success reply: 200 OK, no body.

not-so-REST¶

For interactions that do not directly map onto CRUD, we use these:

GET: Query. Success reply: 200 OK
PUT: Action/Execute. Success reply: 200 OK

Action/Execute methods return a JSON body of this format:

{
  "message": "result message"
}

Authentication¶

The PowerDNS daemons accept a static API Key, configured with the api-key option, which has to be sent in the X-API-Key header.

Errors¶

Response code 4xx or 5xx, depending on the situation. Never return 2xx for an error!

Invalid JSON body from client: 400 Bad Request
JSON body from client not a hash: 400 Bad Request
Input validation failed: 422 Unprocessable Entity

Error responses have a JSON body of this format:

{
  "error": "short error message",
  "errors": [
    {  },
  ]
}

Where errors is optional, and the contents are error-specific.

Common Error Causes¶

400 Bad Request¶

The client body was not a JSON document, or it could not be parsed, or the root element of the JSON document was not a hash.
The client did not send an Accept: header, or it was set to */*.
For requests that operate on a zone, the zone_id URL part was invalid. To get a valid zone_id, list the zones with the /api/v1/servers/:server_id/zones endpoint.