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