Tip #1: Use clear naming
- Choose straigth forward name
- Choose logical name
Example
☒ https://example.com/api/v1/cart/123
☑https://example.com/api/v1/carts/123
Tip #2: Ensure reliability through idempotent APIs
An API request is idempotent if sending it multiple times with the same data results in the same outcome as making it just once. Imagine a light switch: flipping it repeatedly doesn't change the state (on or off). This concept is reliable for APIs.
| Idempotence | |
|---|---|
| HTTP Method | Idempotence |
| POST | No |
| GET | Yes |
| PUT | Yes |
| PATCH | No |
| DELETE | Yes |
Tip #3: Add versioning
Versioning allows updating APIs while supporting backward compatibility. This lets developers using the old versions upgrade on their own timeline. This requires well-documented release note.
Tip #4: Add pagination
Tip #5: Use clear query string for sorting and filtering API data
- GET /users?sort_by=registered
- GET /products?filter=color:blue
- GET /products?filter=size:10&sort_by=data_added
- GET /products?filter=size:10&sort_by=data_added&size:15inches
Tip #6: Don't make security an afterthought when designing APIs
Tip #7: Keep cross-resource references simple
Example
☑ https://example.com/api/v1/carts/123/items/321
☒ https://example.com/api/v1/items?cart_id=123&item_id=321
Tip #8: Plan for rate limiting