Endpoint API actions
| http://api/v1/pets | http://api/v1/pets/8765 | |
|---|---|---|
| GET | List of all pets | Get one pet |
| POST | Create a new pet | – |
| PUT | Replace entire collection | Replace or create a pet |
| DELETE | Delete all pets | Delete one pet |
API endpoints parameters
- Path. Example: `/messages/123`
- Query. Example: `?query=something` or `?categories=cars,helicopters`
- Body. For non-GET requests. Payloads JSON or XML formatted
- Request Header. For example `Origin`
Status codes
1xx
2xx
- 201 – `Created` and also need to put `Location` header into response with link to newly created entity
- 202 – `Accepted` – need to process, the response is not ready yet.
- 204 – `No Content` – if nothing to put into response
- 206 – `Partial content` – When not all content is not returned. For example for pagination purposes. `Link` header is preferable to add links to other endpoints in order to get other parts.
3xx
- 304 – `Not modified` – The resource was not modified since last time
4xx – Some client errors
5xx – Some server errors (in the code)
Caching
Last-Modified
Two headers used in request and response
- Request header `Modified-Since`
- Response header `Last-Modified`
ETag
- Request header `If-None-Match`
- Response header `ETag`
Pagination
- with page number `?page=2&page-size=25`
- with cursor `?cursor=293082` – to continue with “next” entity in the list
- with accept range header: `Accept-Ranges`, `Content-Range`, `Range`
Rate limitation
These headers returns in response:
- `X-RateLimit-Limit: 100` – What is actual limit
- `X-RateLimit-Remaining: 74` – How many requests remaining
- `X-RateLimit-Reset: 12343432432` – When the limit will be reset (timestamp)
Output filtering
- Specify needed fields `?fields=firstname,lastname,address.zip`. Note that there is sub-resource address defined
- Specify excluded fields `?exclude=biography,age`
- Specify style `?style=compact` or `?style=full`
- Request header `Prefer: return=compact`, Response `Preference-Applied: return=compact`
Sorting
- SQL style: `?sort=title+DESC,author+ASC`
Error response format
???
Versioning
- in the URL `https://api.com/v2/member/123`
- In request header: `X-API-Version: 2`
- In Accept header: `Accept: application/vnd.restaurants.v2+json`
Notes
- Never use verbs as entity in URLs. Only nouns allowed as entity names. Verbs good to represent some action on an entity: `/message/13/vote`
- Good to wrapping collection with additional entity in response `{ entity: { … } }`.
- Better to use plural forms of entity names in URLs: `/tickets/123` is better than `/ticket/123`
- Better to use lowercased names (with underscores or dashes)
- Always be consistent with naming whatever style is chosen.
- Id must be UIDs instead of incremental ids. For example: “lwkr23j3i” instead of 1, 2, 3
- Use sub-entities only if these entities cannot be used on itsown. `/tickets/123/messages/23` should be possible only if `messages` cannot be used itself separately.