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

1. 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.
2. The client did not send an Accept: header, or it was set to */*.
3. 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.