rest-api.md

   1 ---
   2 title: RESTful API
   3 updated: 2019-07-07
   4 layout: 2017/sheet
   5 category: API
   6 ---
   7
   8 ### Status codes
   9
  10 | Code                  | Description                                  |
  11 | --------------------- | -------------------------------------------- |
  12 | `200 OK`              | Successful get, patch (return a JSON object) |
  13 | `201 Created`         | Successful post (return a JSON object)       |
  14 | `202 Accepted`        | Successful post, delete, path - async        |
  15 | `204 No content`      | Successful delete                            |
  16 | `206 Partial content` | Successful get - async                       |
  17
  18 ### Error status
  19
  20 | Code                       | Description                       |
  21 | -------------------------- | --------------------------------- |
  22 | `401 Unauthorized`         | Not authenticated                 |
  23 | `403 Forbidden`            | Authenticated, but no permissions |
  24 | `422 Unprocessable entity` | Validation                        |
  25
  26 ### Errors
  27
  28 ```
  29 HTTP/1.1 401 Unauthorized
  30 Content-Type: application/json
  31 {
  32   'id': 'auth_failed',
  33   'message': "You're not logged in."
  34 }
  35 ```
  36
  37 Here's an example of a possible error reply.
  38
  39 ### Versioning
  40
  41 ```
  42 GET /api/foo
  43 Accept: application/json; version=1
  44 ```
  45
  46 You can pass a `version=x` to the Accept request header. [Info here](https://github.com/interagent/http-api-design#version-with-accepts-header)
  47
  48 ### Authentication
  49
  50 ```
  51 curl -is https://$TOKEN@api.example.com/
  52 ```
  53
  54 ### Methods
  55
  56 | Request              | Description                   |
  57 | -------------------- | ----------------------------- |
  58 | `GET /articles/1`    | read, returns _200_           |
  59 | `PUT /articles/1`    | edit (or path), returns _200_ |
  60 | `DELETE /articles/1` | delete, returns _200_         |
  61 | `POST /articles`     | create, returns _201_         |
  62 | `GET /articles`      | list, returns _200_           |
  63
  64 ### References
  65
  66 * [interagent/http-api-design](https://github.com/interagent/http-api-design) _(github.com)_