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
  • 406 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