Route design

// Single-object route

Route: /api/{plural of object}/{id}
       example: /api/people/8
Allowable methods: GET, PATCH, DELETE

// successful response
{
  "id": 8,
  "name": "Alex",
  "alive": true
}


// Multi-object route

Route: /api/{plural of object}
       example: /api/people
Allowable methods: GET, POST

// successful array response
{
  "people": [
    {
      "id": 1,
      "name": "Hugo",
      "alive": true
    },
    {
      "id": 8,
      "name": "Alex",
      "alive": true
    },
    {
      "id": 42,
      "name": "Elvis",
      "alive": false
    }
  ]
}

// Paginated route

Route: /api/{plural of object}?{key}={value}
       example: /api/people?page=2
Allowable methods: GET

// successful response
{
  "page": 0,
  "pageCount": 2,
  "itemCount": 3,
  "perPage": 2,
  "people": [
    {
      "id": 1,
      "name": "Hugo",
      "alive": true
    },
    {
      "id": 8,
      "name": "Alex",
      "alive": true
    }
  ]
}

// Errors
// At some point, I'd like to have unique error codes for each response - for now, we can use the HTTP status (400, 404, etc).

{
  "code": 1234,
  "message": "Some user-friendly text here."
}