API documentation¶
Read this first¶
Foremost you need create token
or use already created when you have
completed sign up process. Token is a random phrase with 32 chars(ascii lowercase + digits).
For testing of API access you can use curl or httpie
command line tools or anything else which can communicate with server over HTTP protocol.
You should specify your token
in HTTP header X-Auth-Token
.
Playing with API¶
Example request with curl
:
$ curl -v -H "X-Auth-Token:4388c735cba9455cae341cbf17ed2198" http://makechat-web/api/rooms
* Hostname was NOT found in DNS cache
* Trying 172.30.1.3...
* Connected to makechat-web (172.30.1.3) port 80 (#0)
> GET /api/rooms HTTP/1.1
> User-Agent: curl/7.35.0
> Host: makechat-web
> Accept: */*
> X-Auth-Token:4388c735cba9455cae341cbf17ed2198
>
< HTTP/1.1 200 OK
* Server nginx/1.9.11 is not blacklisted
< Server: nginx/1.9.11
< Date: Thu, 07 Apr 2016 22:13:14 GMT
< Content-Type: application/json; charset=utf-8
< Content-Length: 304
< Connection: keep-alive
< Cache-Control: max-age=86400, must-revalidate, no-store
< Vary: Accept-Encoding
<
* Connection #0 to host makechat-web left intact
[{"members": [{"$oid": "5706dac4d55cfe00010944ac"}], "is_open": true, "is_visible": true, "_id": {"$oid": "5706dac4d55cfe00010944ad"}, "name": "room1"}, {"members": [{"$oid": "5706dac4d55cfe00010944ac"}], "is_open": true, "is_visible": true, "_id": {"$oid": "5706dac4d55cfe00010944ae"}, "name": "room2"}]$
or less verbose and more readable:
$ curl -s -H "X-Auth-Token:4388c735cba9455cae341cbf17ed2198" http://makechat-web/api/rooms| python -m json.tool
[
{
"_id": {
"$oid": "5706dac4d55cfe00010944ad"
},
"is_open": true,
"is_visible": true,
"members": [
{
"$oid": "5706dac4d55cfe00010944ac"
}
],
"name": "room1"
},
{
"_id": {
"$oid": "5706dac4d55cfe00010944ae"
},
"is_open": true,
"is_visible": true,
"members": [
{
"$oid": "5706dac4d55cfe00010944ac"
}
],
"name": "room2"
}
]
or golden mean by using httpie
:
http -v GET http://makechat-web/api/rooms X-Auth-Token:4388c735cba9455cae341cbf17ed2198
Request:
GET /api/rooms HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: makechat-web
User-Agent: HTTPie/0.9.3
X-Auth-Token: 4388c735cba9455cae341cbf17ed2198
Response:
HTTP/1.1 200 OK
Cache-Control: max-age=86400, must-revalidate, no-store
Connection: keep-alive
Content-Length: 304
Content-Type: application/json; charset=utf-8
Date: Thu, 07 Apr 2016 22:26:12 GMT
Server: nginx/1.9.11
Vary: Accept-Encoding
[
{
"_id": {
"$oid": "5706dac4d55cfe00010944ad"
},
"is_open": true,
"is_visible": true,
"members": [
{
"$oid": "5706dac4d55cfe00010944ac"
}
],
"name": "room1"
},
{
"_id": {
"$oid": "5706dac4d55cfe00010944ae"
},
"is_open": true,
"is_visible": true,
"members": [
{
"$oid": "5706dac4d55cfe00010944ac"
}
],
"name": "room2"
}
]
Note
In examples we will use httpie for interaction with API, because it produces beautiful output with indentation aligned of JSON data.
Examples of bad responses¶
There are many typical mistakes of interaction with API. Do not panic,
just inspect your code one more time and look the API responses more closely:
almost all (except 405 Method Not Allowed error) they have title
and description
,
so you can guess what the problem is.
Request with not valid token or wrong credentials:
Request:
GET /api/rooms HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Connection: keep-alive Host: makechat-web User-Agent: HTTPie/0.9.3 X-Auth-Token: 4388c735cba9455cae341cbf17ed2191
Response:
HTTP/1.1 401 Unauthorized Connection: keep-alive Content-Length: 99 Content-Type: application/json Date: Thu, 07 Apr 2016 22:59:44 GMT Server: nginx/1.9.11 { "description": "Please provide an auth token or login.", "title": "Not authentificated" }
Request with valid token but without admin permissions (for some actions, you need administrator rights):
Request:
GET /api/rooms HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Connection: keep-alive Host: makechat-web User-Agent: HTTPie/0.9.3 X-Auth-Token: 52115268596140298df2a640f37eea57
Response:
HTTP/1.1 403 Forbidden Connection: keep-alive Content-Length: 74 Content-Type: application/json Date: Thu, 07 Apr 2016 23:01:49 GMT Server: nginx/1.9.11 { "description": "Admin required.", "title": "Permission Denied" }
Request with not acceptable content type:
Request:
PUT /api/rooms HTTP/1.1 Accept: */* Accept-Encoding: gzip, deflate Connection: keep-alive Content-Length: 0 Host: makechat-web User-Agent: HTTPie/0.9.3 X-Auth-Token: 52115268596140298df2a640f37eea57
Response:
HTTP/1.1 406 Not Acceptable Connection: keep-alive Content-Length: 267 Content-Type: application/json Date: Thu, 07 Apr 2016 23:21:38 GMT Server: nginx/1.9.11 { "description": "This API only supports responses encoded as JSON.", "link": { "href": "http://docs.examples.com/api/json", "rel": "help", "text": "Documentation related to this error" }, "title": "Media type not acceptable" }
Request with not allowed method:
Request:
PUT /api/rooms HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Connection: keep-alive Content-Length: 18 Content-Type: application/json Host: makechat-web User-Agent: HTTPie/0.9.3 X-Auth-Token: 52115268596140298df2a640f37eea57 { "data": "test" }
Response:
HTTP/1.1 405 Method Not Allowed Connection: keep-alive Content-Length: 0 Date: Thu, 07 Apr 2016 23:22:09 GMT Server: nginx/1.9.11 allow: GET, POST, OPTIONS
Request without required data:
Request:
POST /api/rooms HTTP/1.1 Accept: application/json Accept-Encoding: gzip, deflate Connection: keep-alive Content-Length: 18 Content-Type: application/json Host: makechat-web User-Agent: HTTPie/0.9.3 X-Auth-Token: 4388c735cba9455cae341cbf17ed2198 { "trash": "trash" }
Response:
HTTP/1.1 400 Bad Request Connection: keep-alive Content-Length: 92 Content-Type: application/json Date: Thu, 07 Apr 2016 23:24:52 GMT Server: nginx/1.9.11 { "description": "The 'name' parameter is required.", "title": "Missing parameter" }