Design Principles

Good API design is invisible. When developers use your API and everything just works, that’s the result of deliberate design choices made early and enforced consistently.

Naming Conventions

Your URL structure is your API’s first impression:

# Good — resource-oriented, predictable
GET    /api/v1/articles
GET    /api/v1/articles/42
POST   /api/v1/articles
PATCH  /api/v1/articles/42
DELETE /api/v1/articles/42

# Bad — action-oriented, inconsistent
GET    /api/getArticles
POST   /api/createNewArticle
POST   /api/deleteArticle?id=42

Response Envelopes

Wrap your responses in a consistent structure:

{
  "data": {
    "id": 42,
    "type": "article",
    "attributes": {
      "title": "Design Principles",
      "status": "published"
    }
  },
  "meta": {
    "timestamp": "2026-05-14T10:00:00Z"
  }
}

Error Responses

Errors should be just as structured as success responses:

{
  "error": {
    "code": "validation_failed",
    "message": "Title is required",
    "details": [
      { "field": "title", "rule": "required" }
    ]
  }
}

The sub-parts of this chapter dive deeper into specific patterns — REST conventions and GraphQL basics.