REST API Design Doc

gistfile1.md

REST API Design Doc

Base URL

Each version of the API should remain functional for a period of time after the next version is released to allow client applications time to migrate to the next version. Typically this is done by placing a version number in a query parameter ?version=20151201. If no version is provided, the latest API version will be assumed.

https://company.com/api/

Authentication

Using a combination of HTTPS and BasicAuthentication, we can easily protect the API from unauthorized access. Authentication can be either token based, or username/password based:

https://<user>:<password>@company.com/api/products/BHY3D-01

Resource data are accessible via simple pattern

• List of users: GET /users
• Single user: GET /users/:id

Note: The :id is typically a number, but could be whatever identifier that is easiest to identify a particular item, for products, it may be the SKU or product code.

• Editing a user: PATCH /users/:id

{
  "user": {
    "phone": "123-456-7890"
  }
}

Responses are provided in JSON format

Request: GET /users

Response:

{
  "meta": {
    "page": 1,
    "total_pages": 300
  },
  "data": [
    {
      "url": "/users/1",
      "first_name": "Robert",
      "last_name": "Bousquet"
    }
  ]
}

Request: GET /users/1

Response:

{
  "data": {
    "id": 1,
    "first_name": "Robert",
    "last_name": "Bousquet",
    "email": "robert.bousquet@example.com",
    "phone": "888-555-1212",
    "url": "/users/1"
    // etc.
  }
}