Best practices

Hackernoon

Rester

URLs

Do

Examples

https://www.example.com/api/v1/topics
https://www.example.com/api/v1/users
https://www.example.com/api/v1/articles

1. Version of API should be part of the URL
2. Use plural form to denote the resources

Don't

Examples

https://www.example.com/api/v1/users/topics
https://www.example.com/api/v1/createTopic
https://www.example.com/api/v1/articles/new

1. Do not nest paths to resources
2. Do not use verbs for actions in URLs
3. Do not complicate the URL by using camel case or hyphens

HTTP methods

Use HTTP methods as verbs for actions together with correct HTTP status response codes.

CRUD

Action          Method example URL     Response
-----------------------------------------------
Create          POST /articles         201 CREATED + Location header with /articles/{id}
Read            GET /articles/{id}     200 OK
Update          PUT /articles/{id}     200 OK
Delete          DELETE /articles/{id}  205 NO CONTENT

Partial update  PATCH /articles/{id}   200 OK

Error handling

400 Bad Request     with detailed error message in response body
401 Unauthorized
403 Forbidden
404 Not Found
415 Unsupported Media Type

Message content

Use JSON wherever you can in requests and response content, thus content type should be:

Content-type: application/json; charset=utf-8

Date values should be formatted in ISO 8601 zulu time or Unix time in milliseconds since 1. Jan 1970 UTC.

YYYY-MM-DD
YYYY-MM-DDThh:mm:ss.SSSZ