REST API design principles
Information on using the REST API scheme and principles of its design.
REST API scheme
Common scheme for our REST API is
<VERB> [namespace] <objects> <id> <action>.
namespaceshould scope some specific functionality like
lambda. It is optional in the scheme.
- When you want to extract a specific object from a collection, just specify its
actioncan be used to simplify REST API or provide an endpoint for entities without
data/meta. Note: action should not duplicate other endpoints without a reason.
- Use nouns instead of verbs in endpoint paths. For example,
POST /api/tasksinstead of
- Accept and respond with JSON whenever it is possible
- Name collections with plural nouns (e.g.
- Try to keep the API structure flat. Prefer two separate endpoints
/projects/:id1/tasks/:id2. Use filters to extract necessary information like
/tasks/:id2?project=:id1. In some cases it is useful to get all
tasks. If the structure is hierarchical, it cannot be done easily. Also you have to know both
:id2to get information about the task. Note: for now we accept
GET /tasks/:id2/jobsbut it should be replaced by
/jobs?task=:id2in the future.
- Handle errors gracefully and return standard error codes (e.g.
- Allow filtering, sorting, and pagination
- Maintain good security practices
- Cache data to improve performance
- Versioning our APIs. It should be done when you delete an endpoint or modify
its behaviors. Versioning uses a schema with
Acceptheader with vendor media type.
- Best practices for REST API design
- Flat vs. nested resources
- REST API Design Best Practices for Sub and Nested Resources
- A specification for building APIs in JSON