Jan 25 2014

Practical notes of RESTful API design

by Cem Ikta • Python • Tags: API Design, RESTful Web Services, Web Applications 1

Coding Style in RESTful:

JSON: JavaScript naming conventions: camelCase
Rest clients in Java: camelCase
Rest clients in Python and Ruby: snake_case

RESTful Mapping:

GET /customers => Retrieves a list of customers
GET /customers/{id} => Retrieves a specific customer with id.
GET /customers/5

POST /customers => Creates a new customer

PUT /customers/{id} => Updates customer with id.
PUT /customers/5

PATCH /customers/{id} => Partially updates customer with id.
PATCH /customers/5

DELETE /customers/{id} => Deletes customer with id.
DELETE /customers/5

RESTful Mapping with Relations:

GET /customers/{id}/orders => Retrieves list of orders for customer with id.
GET /customers/5/orders
GET /customers/{id}/orders/{id} => Retrieves order with id for customer with id.
GET /customers/5/orders/23

POST /customers/{id}/orders => Creates a new order in customer with id.
POST /customers/5/orders

PUT /customers/{id}/orders/{id} => Updates order with id for customer with id.
PUT /customers/5/orders/23

PATCH /customers/{id}/orders/{id} => Partially updates order with id for customer with id.
PATCH /customers/5/orders/23

DELETE /customers/{id}/orders/{id} => Deletes order with id for customer with id.
DELETE /customers/5/orders/23

RESTful Mapping with Parameters:

Filtering:

GET /customers?key=value => Retrieves list of customers with key value query parameter.
GET /customers?state=active => Here, state is a query parameter that implements a filter.

Sorting:

GET /customers?sort=value => Retrieves a list of customers with sort parameter.
GET /customers?sort=last_name

GET /customers?sort=value1, value2 => Sort parameter with list of comma separated fields.
GET /customers?sort=last_name, created_at

GET /customers?sort=last_name&dir=DESC => Sorting with two parameters.

Searching:

GET /customers/recently_registered => Simple query.
GET /customers?q=Berlin&state=active&sort=last_name&dir=DESC => Complex query with search, state, sort, dir parameters.

Paging:

GET /customers?page=3&per_page=20 => Paging with parameters.
GET /customers/search/name_starts_with?name=K&sort=name&dir=desc => Paging and sorting with parameters.