Skip to content

Instantly share code, notes, and snippets.

@sixlive
Last active February 10, 2020 18:14
Show Gist options
  • Save sixlive/1e0997f7bade9f7423ccd723c4dbf55e to your computer and use it in GitHub Desktop.
Save sixlive/1e0997f7bade9f7423ccd723c4dbf55e to your computer and use it in GitHub Desktop.
My API Response "Standard"
published: true

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
    }
  }
}
@jesseschutt
Copy link

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?

@sixlive
Copy link
Author

sixlive commented Aug 24, 2017

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"
}

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment