My API Response "Standard"

gistlog.yml

published: true

post.md

Status Codes

Code	Meaning
200	All good!
201	Resource created
302	You were redirected
400	The request was unacceptable (you screwed up)
403	You are not authorized to access the resource
401	You are not authorized
404	Requested resource not found
422	Validation failed (you screwed up)
429	Too many requests hit the API too quickly.
500, 502, 503, 504	Server Errors (we screwed up)

Responses

Error

{
  "message": ""
}

Validation Errors

Validation errors require a bit more context.

{
  "message": "",
  "errors": {
    "url": [
      "The url field is required"
    ],
    "email": [
      "The email field is required"
    ]
  }
}

Single Resource

example.com/resources/{id}

{
  "data": {
    "foo": "bar"
  },
  "meta": {}
}

Collection Resource (paginated)

example.com/resources?page=2

{
  "data": [
    { "foo": "bar" },
    { "baz": "qux" }
  ],
  "meta": {
    "pagination": {
      "count": 15,
      "current_page": 2,
      "links": {
        "next": "http://resources.dev/page?page=2"
      },
      "per_page": 2,
      "total": 61,
      "total_pages": 5
    }
  }
}

Thanks for writing this up! Curious where, and if, you place a message or status key? Does it nest under meta or is it top level?

I don't include a status key, the statues are passed as the HTTP status code.

If there is an error status code (essentially non 2xx) there is only the top level message key.

For example:

GET /resources/{not-actual-id}

Headers

HTTP/1.1 404 Not Found
...

Body

{
   "message": "The resource was not found"
}