cheatsheets/rest-api.md

title
RESTful API

Status codes

• 200 OK - successful get, patch (return a JSON object)
• 201 Created - successful post (return a JSON object)
• 202 Accepted - successful post, delete, path - async
• 204 No content - successful delete
• 206 Partial content - successful get - async

Error status

• 401 Unauthorized - not authenticated
• 403 Forbidden - authenticated but no permissions
• 422 Unprocessable entity - validation

Errors

HTTP/1.1 401 Unauthorized
{
  'id': 'auth_failed',
  'message': "You're not logged in."
}

Versioning (info)

GET /api/foo
Accept: application/json; version=1

Authentication

curl -is https://$TOKEN@api.service.com/

Methods

• GET /articles/1 - read, returns 200
• PUT /articles/1 - edit (or path), returns 200
• DELETE /articles/1 - delete, returns 200
• POST /articles - create, returns 201
• GET /articles - list, returns 200

References

• https://github.com/interagent/http-api-design