RESTful APIs

restful_api.txt

---------------------------------
# REST
Http Method    | Request Payload                | Sample URI               | Response Payload

GET            | -                              | /api/authors             | author collection
                                                  /api/authors/{authorId}  | single author
POST           | single author                  | /api/authors             | single author
PUT            | single author                  | /api/authors/{authorId}  | single author or empty
PATCH          | JsonPatchDocument on author    | /api/authors/{authorId}  | single author or empty
DELETE         | -                              | /api/authors/{authorId}  | -
HEAD           | -                              | /api/authors             | -
                                                  /api/authors/{authorId}  | -
OPTIONS        | -                              | /api/...                 | -

---------------------------------

---------------------------------
# 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
400 Bad Request
401 Unauthorized - not authenticated
403 Forbidden - authenticated but no permissions
406 Not Acceptable - if client requests in XML and api does not have the option to respond in XML
409 Conflict - try to create a resource that already exists
415 Unsupported Media Type - if client try to post object in XML and the server does not support that media type
422 Unprocessable entity - validation, if client try to post object with a required field as null, it should respond with an error object with {"title": ["title is mandatory"]}

500 Internal Server Error

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

src: https://devhints.io/rest-api
---------------------------------


Other References:
https://www.restapitutorial.com/lessons/restquicktips.html

PATCH correct usage:
https://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/

REST Resource Naming Guide
https://restfulapi.net/resource-naming/

Richardson Maturity Model
https://martinfowler.com/articles/richardsonMaturityModel.html

kcassam/api design.md
https://gist.github.com/kcassam/1f6caf1e8dde9d54fd30

downzer0/api-standards.md
https://gist.github.com/downzer0/af6efe2fd47c74a9172631d2dfed4cd3