← Systems Analysis: APIs, Integrations and Data
Lesson
HTTP requests and REST resources through a designer's eyes
Break an HTTP request and response down into their parts and design the REST resource addresses for the case: plural nouns, hierarchy, path and query parameters.
Request, response and resources
Request, response and resources
A refresher from the testing course: an HTTP request has a method, an address (URI: path and query parameters), headers and a body; a response has a status code, headers and a body. HTTP does not remember past requests (it is stateless): each request carries everything the server needs, including the token.
REST is an architectural style (Roy Fielding, 2000), not a data format: each resource has its own address, methods mean the same for all resources (a uniform interface), the server keeps no conversation state, responses can be cached. Data travels as JSON, XML or another format. “REST = JSON” is a misconception: JSON is just more common.
Address rules:
• a resource is a plural noun: /orders;
• a specific resource, by its identifier: /orders/9001;
• a nested one, if it belongs to a parent: /orders/9001/items;
• the method expresses the action, not a verb in the path: not /getOrder, not /createOrder. The exception is an action beyond “create, read, update, delete”, such as cancelling: POST /orders/9001/cancel (more in the next lesson).
A path parameter says which resource you need: 9001 in /orders/9001. A query parameter follows “?” and filters, sorts or pages a list: /orders?customerId=42&status=delivered — customer 42's orders with the status delivered.
The headers an analyst writes into the contract are in the table below. Idempotency-Key will join them later.
Good and bad addresses
| Task | Do | Don't |
|---|---|---|
| get an order | GET /v1/orders/9001 | GET /v1/getOrder?id=9001 |
| create an order | POST /v1/orders | POST /v1/orders/create |
| order items | GET /v1/orders/9001/items | GET /v1/orderItems?order=9001&all=true |
| paid orders | GET /v1/orders?status=paid | GET /v1/orders/paid |
Headers in the contract
| Header | What it carries |
|---|---|
| Content-Type | body format: application/json |
| Accept | the format in which the client expects the response |
| Authorization | the client's token |
| Location | address of the created resource: /v1/orders/9001 |
| Retry-After | how long to wait before retrying the request |
Lesson notes
Request, response and resources
A refresher from the testing course: an HTTP request has a method, an address (URI: path and query parameters), headers and a body; a response has a status code, headers and a body. HTTP does not remember past requests (it is stateless): each request carries everything the server needs, including the token.
REST is an architectural style (Roy Fielding, 2000), not a data format: each resource has its own address, methods mean the same for all resources (a uniform interface), the server keeps no conversation state, responses can be cached. Data travels as JSON, XML or another format. “REST = JSON” is a misconception: JSON is just more common.
Address rules:
• a resource is a plural noun: /orders;
• a specific resource, by its identifier: /orders/9001;
• a nested one, if it belongs to a parent: /orders/9001/items;
• the method expresses the action, not a verb in the path: not /getOrder, not /createOrder. The exception is an action beyond “create, read, update, delete”, such as cancelling: POST /orders/9001/cancel (more in the next lesson).
A path parameter says which resource you need: 9001 in /orders/9001. A query parameter follows “?” and filters, sorts or pages a list: /orders?customerId=42&status=delivered — customer 42's orders with the status delivered.
The headers an analyst writes into the contract are in the table below. Idempotency-Key will join them later.