doc: initial REST API doc draft
This commit is contained in:
Thomas Gelf
parent
7f558d1523
commit
9bbdb6f983
|
|
@ -0,0 +1,166 @@
|
||||||
|
The Icinga Director REST API
|
||||||
|
============================
|
||||||
|
|
||||||
|
Introduction
|
||||||
|
------------
|
||||||
|
|
||||||
|
Icinga Director has been designed with a REST API in mind. Most URLs you
|
||||||
|
can access with your browser will also act as valid REST url endpoints.
|
||||||
|
|
||||||
|
Base Headers
|
||||||
|
------------
|
||||||
|
All your requests MUST have a valid accept header. The only acceptable
|
||||||
|
variant right now is `application/json`, so please always append a header
|
||||||
|
as follows to your requests:
|
||||||
|
|
||||||
|
Accept: application/json
|
||||||
|
|
||||||
|
|
||||||
|
Authentication
|
||||||
|
--------------
|
||||||
|
Please use HTTP authentication and any valid Icinga Web 2 user, granted
|
||||||
|
enough permissions to accomplish the desired actions. The restrictions
|
||||||
|
and permissions that have been assigned to web users will also be enforced
|
||||||
|
for API users. In addition, the permission `director/api` is required for
|
||||||
|
any API access.
|
||||||
|
|
||||||
|
Versioning
|
||||||
|
----------
|
||||||
|
|
||||||
|
Many REST APIs include version strings in their URLs, Icinga Director
|
||||||
|
doesn't. We will try hard to not break compatibility with future versions.
|
||||||
|
Sure, sooner or later we also might be forced to introduce some kind of
|
||||||
|
versioning. But who knows? So we decided to not pollute our beautiful URLs
|
||||||
|
with ugly extensions like /v1/.
|
||||||
|
|
||||||
|
As a developer you can trust us to not remove any existing REST url or any
|
||||||
|
provided property. However, you must always be ready to accept new properties.
|
||||||
|
|
||||||
|
URL scheme and supported methods
|
||||||
|
--------------------------------
|
||||||
|
|
||||||
|
POST director/host
|
||||||
|
gives 201 on success
|
||||||
|
GET director/host?name=hostname.example.com
|
||||||
|
PUT director/host?name=hostname.example.com
|
||||||
|
gives 200 ok on success and 304 not modified on no change
|
||||||
|
DELETE director/host?name=hostname.example.com
|
||||||
|
gives 200 on success
|
||||||
|
|
||||||
|
|
||||||
|
First example request with CURL
|
||||||
|
-------------------------------
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -H 'Accept: application/json' \
|
||||||
|
-u 'username:password' \
|
||||||
|
'https://icinga.example.com/icingaweb2/director/host?name=hostname.example.com'
|
||||||
|
```
|
||||||
|
|
||||||
|
Should I use HTTPS?
|
||||||
|
-------------------
|
||||||
|
|
||||||
|
Sure, absolutely, no doubt. There is no, absolutely no reason to NOT use
|
||||||
|
HTTPS these days. Especially not for a configuration tool allowing you to
|
||||||
|
configure check commands that are going to be executed on all your servers.
|
||||||
|
|
||||||
|
Icinga Objects
|
||||||
|
--------------
|
||||||
|
|
||||||
|
### Special parameters
|
||||||
|
|
||||||
|
#### Resolve object properties
|
||||||
|
|
||||||
|
In case you add the `resolve` parameter to your URL, all inherited object
|
||||||
|
properties will be resolved. Such a URL could look as follows:
|
||||||
|
|
||||||
|
director/host?name=hostname.example.com&resolve
|
||||||
|
|
||||||
|
|
||||||
|
#### Retrieve all properties
|
||||||
|
|
||||||
|
Per default properties with `null` value are skipped when shipping a result.
|
||||||
|
You can influence this behavior with the properties parameter. Just append
|
||||||
|
`properties=ALL` to your URL:
|
||||||
|
|
||||||
|
director/host?name=hostname.example.com&properties=all
|
||||||
|
|
||||||
|
|
||||||
|
#### Retrieve only specific properties
|
||||||
|
|
||||||
|
The `properties` parameter also allows you to specify a list of specific
|
||||||
|
properties. In that case, only the given properties will be returned, even
|
||||||
|
when they have no (`null`) value:
|
||||||
|
|
||||||
|
director/host?name=hostname.example.com&properties=object_name,address,vars
|
||||||
|
|
||||||
|
|
||||||
|
Example
|
||||||
|
-------
|
||||||
|
|
||||||
|
director/host?name=pe2015.example.com&json
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"address": "127.0.0.3",
|
||||||
|
"check_command": null,
|
||||||
|
"check_interval": null,
|
||||||
|
"display_name": "pe2015 (example.com)",
|
||||||
|
"enable_active_checks": null,
|
||||||
|
"flapping_threshold": null,
|
||||||
|
"groups": [ ],
|
||||||
|
"imports": [
|
||||||
|
"generic-host"
|
||||||
|
],
|
||||||
|
"retry_interval": null,
|
||||||
|
"vars": {
|
||||||
|
"facts": {
|
||||||
|
"aio_agent_build": "1.2.5",
|
||||||
|
"aio_agent_version": "1.2.5",
|
||||||
|
"architecture": "amd64",
|
||||||
|
"augeas": {
|
||||||
|
"version": "1.4.0"
|
||||||
|
},
|
||||||
|
...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
director/host?name=pe2015.example.com&json&resolved
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"address": "127.0.0.3",
|
||||||
|
"check_command": "tom_ping",
|
||||||
|
"check_interval": "60",
|
||||||
|
"display_name": "pe2015 (example.com)",
|
||||||
|
"enable_active_checks": true,
|
||||||
|
"groups": [ ],
|
||||||
|
"imports": [
|
||||||
|
"generic-host"
|
||||||
|
],
|
||||||
|
"retry_interval": "10",
|
||||||
|
"vars": {
|
||||||
|
"facts": {
|
||||||
|
"aio_agent_build": "1.2.5",
|
||||||
|
"aio_agent_version": "1.2.5",
|
||||||
|
"architecture": "amd64",
|
||||||
|
"augeas": {
|
||||||
|
"version": "1.4.0"
|
||||||
|
},
|
||||||
|
...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
TODO
|
||||||
|
----
|
||||||
|
|
||||||
|
Return Last-Modified und ETag header?
|
||||||
|
-> If-Modified-Since -> mtime?
|
||||||
|
-> If-Unmodified-Since -> mtime
|
||||||
|
|
||||||
|
|
||||||
|
SHA1 sum as ETag? For PUT and DELETE:
|
||||||
|
-> If-Match -> SHA1 sum as ETag?!
|
||||||
|
-> If-None-Match -> SHA1 sum as ETag?!
|
||||||
|
|
||||||
|
|
||||||
|
304, 412
|
||||||
|
|
||||||
Loading…
Reference in New Issue