Commit e17f54c9 authored by Łukasz Nowak's avatar Łukasz Nowak

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.
parent 15ff6551
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
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment