REST API Design Principles

Охватываемые темы: Resources and URLs, HTTP methods, Nested resources, Response codes.

Resources and URLs

A URL should represent a resource (a noun), not an action:

# Bad (action in the URL)
GET /getTasks
POST /createTask
DELETE /deleteTask/1

# Good (resource + HTTP method = action)
GET /tasks
POST /tasks
DELETE /tasks/1

HTTP methods

Nested resources

GET /projects/5/tasks           # tasks of project 5
POST /projects/5/tasks          # create a task in project 5
GET /projects/5/tasks/10        # a specific task within a project

Response codes

200 OK              — success (GET, PUT, PATCH)
201 Created         — created (POST)
204 No Content      — deleted (DELETE)
400 Bad Request     — malformed request
401 Unauthorized    — not authenticated
403 Forbidden       — insufficient permissions
404 Not Found       — resource not found
422 Unprocessable   — validation error
500 Server Error    — server-side error

Filtering, sorting, pagination

GET /tasks?status=todo              # filtering
GET /tasks?ordering=-created_at     # sorting
GET /tasks?page=2&page_size=20      # pagination
GET /tasks?search=important+task    # search

Response format

// List
{
  "count": 42,
  "next": "http://api.example.com/tasks/?page=2",
  "previous": null,
  "results": [
    {"id": 1, "title": "Task", "status": "todo"}
  ]
}

// Error
{
  "error": "validation_error",
  "message": "Title is required",
  "field": "title"
}

Versioning

/api/v1/tasks/    # version in the URL (most common approach)
/api/v2/tasks/

# Or via header:
Accept: application/vnd.myapi.v1+json