github.com/cozy/cozy-stack@v0.0.0-20240603063001-31110fa4cae1/docs/http-api.md (about) 1 [Table of contents](README.md#table-of-contents) 2 3 # Using the HTTP API of cozy-stack 4 5 ## HTTP Codes 6 7 The developers of cozy-stack are trying to respect the semantics of HTTP, and 8 the HTTP response code is symbolic of that. The stack uses a large range of 9 HTTP codes, but the most common ones are: 10 11 - `200 OK` for a successful operation, with information in the HTTP body 12 - `201 Created` for a document successfully created 13 - `204 No Content` for a success with no relevant information to send (like a successful deletion) 14 - `400 Bad Request` when the request is incorrect 15 - `401 Unauthorized` when no authorization has been sent, or the token is expired 16 - `402 Payment Required` when the instance has been blocked and a [user action is required](./user-action-required.md) (payment, or validating the Terms of Services) 17 - `403 Forbidden` when the authorization has been sent, is valid, but does not grant access to the resource 18 - `404 Not Found` when the resource is not found 19 - `409 Conflict` when there is a conflict on the managed resource 20 - `410 Gone` when a Cozy instance has been moved to a new address 21 - `412 Precondition Failed` when a parameter from the HTTP headers or query string is invalid 22 - `422 Unprocessable entity` when an attribute in the HTTP request body is invalid 23 - `500 Internal Server Error` when something went wrong on the server (bug, network issue, unavailable database) 24 - `502 Bad Gateway` when an HTTP service used by the stack is not available (apps registry, OIDC provider) 25 26 ## JSON-API 27 28 ### Introduction 29 30 Except for the routes in `/data`, which imitate couchdb, most of the stack 31 exposes a JSON-API interface. 32 33 See [JSON-API specification](http://jsonapi.org/format/) for more information. 34 35 ### Pagination 36 37 All routes that return a list are (or will be) paginated. 38 39 As recommended for couchdb, we use **cursor-based** pagination. 40 41 The default page limit is determined on a by-route basis. The client can require 42 a different limit using `page[limit]` query parameter. If the client does not 43 specify a limit, default limit will be used instead. 44 45 If there is more docs after the limit, the response will contain a `next` key in 46 its links section, with a `page[cursor]` set to fetch docs starting after the 47 last one from current request. 48 49 Alternatively, the client can opt in for skip mode by using `page[skip]`. When 50 using skip, the number given in `page[skip]` is number of element ignored before 51 returning value. Similarly, the response will contain a next link with a 52 `page[skip]` set for next page (skip + limit). 53 54 #### Example 55 56 The `/relationships/references` as a default limit of 100. 57 58 ```http 59 GET /data/some-type/some-id/relationships/references HTTP/1.1 60 ``` 61 62 ```json 63 { 64 "data": ["... 100 docs ..."], 65 "links": { 66 "next": "/data/some-type/some-id/relationships/references?page[limit]=100&page[cursor]=7845122548848454212" 67 } 68 } 69 ``` 70 71 ```http 72 GET /data/some-type/some-id/relationships/references?page[limit]=10 HTTP/1.1 73 ``` 74 75 ```json 76 { 77 "data": ["... 10 docs ..."], 78 "links": { 79 "next": "/data/some-type/some-id/relationships/references?page[limit]=10&page[cursor]=5487ba7596" 80 } 81 } 82 ``` 83 84 ```http 85 GET /data/some-type/some-id/relationships/references?page[limit]=100&page[cursor]=7845122548848454212 HTTP/1.1 86 ``` 87 88 ```json 89 { 90 "data": ["... 20 docs ..."] 91 } 92 ``` 93 94 ```http 95 GET /data/some-type/some-id/relationships/references?page[limit]=10&page[skip]=0 HTTP/1.1 96 ``` 97 98 ```json 99 { 100 "data": ["... 10 docs ..."], 101 "links": { 102 "next": "/data/some-type/some-id/relationships/references?page[limit]=10&page[skip]=10" 103 } 104 } 105 ```