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  ```