Reference

resources:

• there should not be different ways to achieve the same action
• one resource = one URL leads to proliferation : person => adress => country / But don't end being too verbose (clarity and bandwith consuming)
• 2 nested levels maximum = > users/addresses/countries is OK
• emebedded collections should not have many components (eg. 10)
• semantic grouping (address)

URL:

• API: – https://api.{fakecompany}.com
• OAuth2 – https://oauth2.{fakecompany}.com
• Developer portal – https://developers.{fakecompany}.com

Verbs and resources:

• no verbs
• relate to resource
• use pluarl, because we operate on collections
• use spinal-case (kebab-case)
• expose major version number at API URL first level: api.test.com/v2/my-resource (and support 2)
• use {} as placeholder for parameter: my-collection/{id}

Samples:

• read => getClient(1) => GET /clients/1
• create (no id)=> createClient => POST /clients
• update
  • partial (eg. status) => updateAccountBalance(1) => PATCH /accounts/1
  • full => addProductToOrder(1) => PUT /orders/1
• delete => deleteAddress(1) => DELETE /addresses/1

Paths:

• GET
  • Good
    • OK=> 200
    • OK with partial (paging) and actual < paging size => 206 (Partial Content)
  • Bad
    • incorrect paging => 400 Bad request
    • incorrect params => 400 Bad request
    • content (type) not supported => 406
• POST
• OK => 201 + URI in response's Location header

Partial answers (paging)

• specify properties
• sepcifiy instance count, start at index, count before or after
• default values: 0 to 25
• in parameter or header ?

Content:

• XML
• JSON