Lunching for groups.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 

88 lines
2.2 KiB

About the API
==============
A few things you must know before diving into the API:
Everything is JSON
-------------------
Every request should have a JSON payload; anything else will be refused and
return a 400 status. For example:
.. sourcecode:: http
POST /randomendpoint
Host: example.com
Accept: text/html
Content-Type: application/x-www-form-urlencoded
field1=value&field2=value
The response will always be:
.. sourcecode:: http
HTTP/1.1 400 Bad Request
Content-Type: application/json
{ "status": "ERROR", "message": "Request MUST be in JSON format" }
If instead you do a proper JSON request with:
.. sourcecode:: http
POST /randomendpoint
Host: example.com
Content-type: application/json
{ "field1": "value", "field2": "value" }
Then everything would go fine.
Standard responses
-------------------
Responses will always have a ``status`` parameter with the result of the
operation -- more fields may be also returned, depending on the request.
Successful requests with have the value ``OK`` for ``status`` -- and, again,
more fields may be returned in most cases. Also, the HTTP status code will
**always** be 200.
In case of failure, ``status`` will have the text ``ERROR`` (in all caps) and
a ``message`` field will have the reason for the error -- and, as success, it
may contain more fields with information about the error. For different errors
in the operation there will be a different HTTP status. We tried as hard as
possible to give each error a meaningful HTTP status, even if this sometimes
wouldn't make much sense -- for example, if you try to change the ownership of
a group and the group doesn't exist, you'll get a 404 status; if the new owner
doesn't exist, instead of a proper 404, we will return a 412 status, not
because there is a precondition error in the headers, but because we need
a different code to point that the new user does not exist.
Redirects
----------
All URLs must end with "/"; if you forget to add them in the URL, you'll
receive a redirect to the path with "/".
Flow
=====
Here are some expected typical request flows:
.. toctree::
:maxdepth: 3
flow/voting
API
====
.. toctree::
:maxdepth: 3
users_and_tokens
places
groups
voting