Drop introspection.

The API shall be simple, yet powerful. Introspection seemed like cool idea, but
is not required.

There are limited amount of endpoints. There are few parameters. Those things
shall be documented.

Backward compatibility is easy. Adding new endpoint or parameter shall be always
optional.

In case of rewriting versioning will be used.

documentation/source/rest.rst

 SlapOS Master REST API (v1)
 ***************************
 
+Introduction
+------------
+
+This is so called REST interface to Vifib which uses HTTP protocol.
+
+API_BASE
+++++++++
+
+``"API_BASE"`` is server side path of the interface. In case of Vifib.net it
+is...
+
 Authentication
 --------------
 
@@ -25,7 +36,7 @@ They were not implemented as begin fragile from security point of view.
 
 Example of using Bearer token::
 
-  GET /api/v1/instance/{instance_id} HTTP/1.1
+  GET /API_BASE/instance/{instance_id} HTTP/1.1
   Host: example.com
   Accept: application/json
   Authorization: Bearer 7Fjfp0ZBr1KtDRbnfVdmIw
@@ -42,14 +53,14 @@ access tokens.  Client shall fetch `access_token` as described in:
 
 Such token shall be passed in `Authorization` header, in case of Facebook::
 
-  GET /api/v1/instance/{instance_id} HTTP/1.1
+  GET /API_BASE/instance/{instance_id} HTTP/1.1
   Host: example.com
   Accept: application/json
   Authorization: Facebook retrieved_access_token
 
 and in case of Google::
 
-  GET /api/v1/instance/{instance_id} HTTP/1.1
+  GET /API_BASE/instance/{instance_id} HTTP/1.1
   Host: example.com
   Accept: application/json
   Authorization: Google retrieved_access_token
@@ -148,97 +159,6 @@ Request to non existing resource made.
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 Unexpected error.
 
-Introsepcation Methods
-**********************
-
-Fetching list of access urls
-----------------------------
-
-Explain access points in dictionary.
-
-Client is expected to ask about connection points before doing any request.
-
-In case if required mapping is defined on client side, but server does not
-expose this information, it means, that such capability is not available on
-server side and should not be used.
-
-In case if client does not support exposed mapping it is allowed to ignore
-them.
-
-Client shall be aware that one API can be spanned across many servers and that
-all urls are given as absolute ones.
-
-Endpoint to invoke required action is in ``url`` object, where values in
-``{}`` shall be replaced with corresponding access urls. For example
-``instance_url`` shall be replaced with obtained URL of instance (by request
-or list).
-
-``method`` is required method on URL.
-
-All required parameters, if any, are in ``required`` object.
-
-All optional understandable parameters, if any, are in ``optional`` object.
-
-In case if access point requires authentication, then ``authentication`` will be set to ``true``.
-
-`Request`::
-
-  GET / HTTP/1.1
-  Host: example.com
-  Accept: application/json
-
-`No Expected Request Body`
-
-Extract of possible response::
-
-  HTTP/1.1 200 OK
-  Content-Type: application/json; charset=utf-8
-
-  {
-    "instance_bang": {
-      "authentication": true,
-      "url": "{instance_url}/bang",
-      "method": "POST",
-      "required": {
-        "log": "unicode"
-      },
-      "optional": {}
-    },
-    "instance_list": {
-      "authentication": true,
-      "url": "http://three.example.com/instance",
-      "method": "GET",
-      "required": {},
-      "optional": {}
-    },
-    "register_computer": {
-      "authentication": true,
-      "url": "http://two.example.com/computer",
-      "method": "POST",
-      "required": {
-        "title": "unicode"
-      },
-    },
-    "request_instance": {
-      "authentication": true,
-      "url": "http://one.example.com/instance",
-      "method": "POST",
-      "required": {
-         "status": "unicode",
-         "slave": "bool",
-         "title": "unicode",
-         "software_release": "unicode",
-         "software_type": "unicode",
-         "parameter": "object",
-         "sla": "object"
-      },
-      "optional": {}
-    }
-  }
-
-All documentation here will refer to named access points except otherwise
-stated. The access point will appear in ``[]`` after method name.
-
 Instance Methods
 ****************
 
@@ -249,7 +169,7 @@ Ask for list of instances.
 
 `Request`::
 
-  GET [instance_list] HTTP/1.1
+  GET /API_BASE/instance HTTP/1.1
   Host: example.com
   Accept: application/json
 
@@ -277,7 +197,7 @@ Request a new instantiation of a software.
 
 `Request`::
 
-  POST [request_instance] HTTP/1.1
+  POST /API_BASE/instance HTTP/1.1
   Host: example.com
   Accept: application/json
   Content-Type: application/json; charset=utf-8
@@ -342,7 +262,7 @@ Request all instance information.
 
 `Request`::
 
-  GET [instance_info] HTTP/1.1
+  GET /API_BASE/<instance_path> HTTP/1.1
   Host: example.com
   Accept: application/json
 
@@ -395,7 +315,7 @@ Request the instance certificates.
 
 `Request`::
 
-  GET [instance_certificate] HTTP/1.1
+  GET /API_BASE/<instance_path>/certificate HTTP/1.1
   Host: example.com
   Accept: application/json
 
@@ -427,7 +347,7 @@ Trigger the re-instantiation of all partitions in the instance tree
 
 `Request`::
 
-  POST [instance_bang] HTTP/1.1
+  POST /API_BASE/<instance_path>/bang HTTP/1.1
   Host: example.com
   Accept: application/json
   Content-Type: application/json; charset=utf-8
@@ -453,7 +373,7 @@ Modify the instance information and status.
 
 `Request`::
 
-  PUT [instance_edit] HTTP/1.1
+  PUT /API_BASE/<instance_path> HTTP/1.1
   Host: example.com
   Accept: application/json
   Content-Type: application/json; charset=utf-8
@@ -504,7 +424,7 @@ Add a new computer in the system.
 
 `Request`::
 
-  POST [register_computer] HTTP/1.1
+  POST /API_BASE/computer HTTP/1.1
   Host: example.com
   Accept: application/json
   Content-Type: application/json; charset=utf-8
@@ -538,7 +458,7 @@ Get the status of a computer
 
 `Request`::
 
-  GET [computer_info] HTTP/1.1
+  GET /API_BASE/<computer_path> HTTP/1.1
   Host: example.com
   Accept: application/json
 
@@ -584,7 +504,7 @@ Modify computer information in the system
 
 `Request`::
 
-  PUT [computer_edit] HTTP/1.1
+  PUT /API_BASE/<computer_path> HTTP/1.1
   Host: example.com
   Accept: application/json
   Content-Type: application/json; charset=utf-8
@@ -627,7 +547,7 @@ Request to supply a new software release on a computer
 
 `Request`::
 
-  POST [computer_supply] HTTP/1.1
+  POST /API_BASE/<computer_path>/supply HTTP/1.1
   Host: example.com
   Accept: application/json
   Content-Type: application/json; charset=utf-8
@@ -654,7 +574,7 @@ Request update on all partitions
 
 `Request`::
 
-  POST [computer_bang] HTTP/1.1
+  POST /API_BASE/<computer_path>/bang HTTP/1.1
   Host: example.com
   Accept: application/json
   Content-Type: application/json; charset=utf-8
@@ -680,7 +600,7 @@ Report computer usage
 
 `Request`::
 
-  POST [computer_report] HTTP/1.1
+  POST /API_BASE/<computer_path>/report HTTP/1.1
   Host: example.com
   Accept: application/json
   Content-Type: application/json; charset=utf-8