Practical Notes of RESTful API Design

Coding Style in RESTful:

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

RESTful URL 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 URL 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 URL 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.

 

Original post is from my old devsniper.com blog!

 

* Image credit: Designed by Freepik