From 9bbdb6f9831ea3775bfbdaa4664ce4ba53331c29 Mon Sep 17 00:00:00 2001
From: Thomas Gelf <thomas@gelf.net>
Date: Thu, 10 Dec 2015 19:54:45 +0100
Subject: [PATCH] doc: initial REST API doc draft

---
 doc/70-REST-API.md | 166 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)
 create mode 100644 doc/70-REST-API.md

diff --git a/doc/70-REST-API.md b/doc/70-REST-API.md
new file mode 100644
index 00000000..cbaecd8b
--- /dev/null
+++ b/doc/70-REST-API.md
@@ -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
+