REST API best practices - AADevTeam/docs GitHub Wiki

Even though the Assessments module does not provide a public API at the moment, the client-server communication happens via a RESTful API. This API is maintained keeping the following best practices in mind.

All the operations should be RESTful

Use GET, POST, PUT, PATCH, DELETE calls in their normal senses. For example,

GET /tickets - Retrieves a list of tickets
GET /tickets/12 - Retrieves a specific ticket
POST /tickets - Creates a new ticket
PUT /tickets/12 - Updates ticket #12
PATCH /tickets/12 - Partially updates ticket #12
DELETE /tickets/12 - Deletes ticket #12

For non-CRUD operations, use one of the following options:

  1. Restructure the field as a resource, then PATCH. For example, to mark an assessment as done, use /assessments/:id/done.
  2. As used in the Github API, use verbs with PUT. Eg: /gist/:id/star
  3. When no other options exist, use a separate call like /search.

Wording

All the endpoints names should be in plural (eg: tickets, assessments).

snake_case is used for multiple words (eg: planned_assessments).

Creation and Updates should return a resource representation

These include POST, PATCH and PUT calls. For example, a POST call may return a 201 response along with a location URL that points to the new resource.

Filtering

GET /assessments?state=open

Sorting

GET /assessments?sort=-priority,created_at

Searching

Use a combination of filtering and sorting for general searching.

GET /assessments?state=closed&sort=updated_at
GET /assessments?q=return&state=open&sort=-priority,created_at

Use aliases for commonly used queries.

GET /assessments/recently_created