Servers

The server endpoint is the ‘basis’ for all other API operations. In the PowerDNS Authoritative Server, the server_id is always localhost. However, the API is written in a way that a proxy could be in front of many servers, each with their own server_id.

Endpoints

GET /servers

List all servers

Status Codes:

• 200 OK – An array of servers Returns: array of Server objects
• 400 Bad Request – The supplied request was not valid Returns: Error object
• 404 Not Found – Requested item was not found Returns: Error object
• 422 Unprocessable Entity – The input to the operation was not valid Returns: Error object
• 500 Internal Server Error – Internal server error Returns: Error object

GET /servers/{server_id}

List a server

Parameters:

• server_id (string) – The id of the server to retrieve

Status Codes:

• 200 OK – An server Returns: Server object
• 400 Bad Request – The supplied request was not valid Returns: Error object
• 404 Not Found – Requested item was not found Returns: Error object
• 422 Unprocessable Entity – The input to the operation was not valid Returns: Error object
• 500 Internal Server Error – Internal server error Returns: Error object

Objects

Server

Object Properties:  

• type (string) – Set to “Server”
• id (string) – The id of the server, “localhost”
• daemon_type (string) – “recursor” for the PowerDNS Recursor and “authoritative” for the Authoritative Server
• version (string) – The version of the server software
• url (string) – The API endpoint for this server
• config_url (string) – The API endpoint for this server’s configuration
• zones_url (string) – The API endpoint for this server’s zones

Examples

Listing all servers

GET /api/v1/servers HTTP/1.1
X-API-Key: secret

Will yield a response similar to this (several headers omitted):

HTTP/1.1 200 OK
Content-Type: application/json

[{"autoprimaries_url": "/api/v1/servers/localhost/autoprimaries{/autoprimary}", "config_url": "/api/v1/servers/localhost/config{/config_setting}", "daemon_type": "authoritative", "id": "localhost", "type": "Server", "url": "/api/v1/servers/localhost", "version": "4.6.1", "zones_url": "/api/v1/servers/localhost/zones{/zone}"}]

Listing a server

GET /api/v1/servers/localhost HTTP/1.1
X-API-Key: secret

Will yield a response similar to this (several headers omitted):

HTTP/1.1 200 OK
Content-Type: application/json

{"autoprimaries_url": "/api/v1/servers/localhost/autoprimaries{/autoprimary}", "config_url": "/api/v1/servers/localhost/config{/config_setting}", "daemon_type": "authoritative", "id": "localhost", "type": "Server", "url": "/api/v1/servers/localhost", "version": "4.6.1", "zones_url": "/api/v1/servers/localhost/zones{/zone}"}