1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
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:
.. code-block:: json
[
{
"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:
.. code-block:: json
{
"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:
.. code-block:: json
{
"message": "result message"
}
Authentication
--------------
The PowerDNS daemons accept a static API Key, configured with the :ref:`setting-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:
.. code-block:: json
{
"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.
|
