REST API Design

Practice

Use case

• Order (number, date)
  • has one Customer
  • has one or more Items
  • has zero or more Tags
• Customer (number, name, country)
• Item (number, product, quantity)
  • Items exist only within Orders
• Tag (name, description)

Rules

• Be consistent.
• Utilize HTTP features (verbs, status codes, headers).
• Use hypermedia.
• Define filtering, sorting and pagination on collections.
• API endpoints should return:
  • a single resource or ...
  • a collection of resources or ...
  • an error (or redirect) and ...
  • nothing else!

Steps

1. Identifying resource
2. Specifying operations
3. Considering query parameters
4. Defining status codes
5. Specifying headers
6. Choosing data representation