rest-api.md

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