RESTful API Design Principles

Design an API contract before writing handlers

An API contract tells clients which resources exist, which operations are allowed and how success or failure is represented. For a learning platform, exams, questions and attempts are resources. Consistent rules make a frontend easier to maintain and reduce accidental exposure of private data.

Map operations to HTTP

• GET /api/v1/exams lists available exams; GET /api/v1/exams/12 reads one.
• POST /api/v1/exams creates an exam and returns 201 with a Location header identifying the new resource.
• PUT /api/v1/exams/12 replaces its editable representation according to a documented contract.
• PATCH /api/v1/exams/12 changes selected allowed fields.
• DELETE /api/v1/exams/12 removes it; a 204 response has no body.

GET should not change server state. PUT and DELETE have idempotent intended effects: repeating them does not keep creating new changes. Their repeated response statuses need not be identical. POST is not inherently idempotent; retry-sensitive actions such as payment or attempt submission need an explicit deduplication design.

Use predictable representations

// Successful collection response
{
  "data": [{ "id": 12, "title": "Node Foundations" }],
  "page": { "limit": 20, "nextCursor": null }
}

// Validation error response
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "title must contain 1–120 characters",
    "field": "title"
  }
}

Use 400 for an invalid request, 401 when valid authentication is required, 403 when the authenticated caller lacks permission, 404 for an unavailable resource, 409 for a state conflict, and 500 for an unexpected server failure. Document your exact choices. A client should inspect status and machine-readable code rather than parse an English sentence.

Pagination and access rules

Bound collection size and define a stable order, such as createdAt plus id. Cursor pagination is useful when the collection changes during browsing. Validate filters and map sorting fields through an allowlist; do not copy them into database syntax. Return only fields the caller may see. A public exam summary should not contain correct answers, unpublished questions, student emails or internal moderation notes.

Prevent conflicting changes

Two editors can overwrite each other's work even when both requests are individually valid. For important updates, use a version or ETag with conditional requests and reject stale writes. Distinguish “resource exists” from “caller owns resource.” Check ownership on each object operation rather than relying on an unguessable ID.

Write the acceptance checklist

For POST /api/v1/exams, specify allowed fields, title limits, authorization, 201 response shape, Location header and duplicate handling before implementation. Try a missing title, an unexpected admin field, a large body and an unauthorized caller. An OpenAPI description can record the contract, but it must match actual behavior.

Practice: design an attempt-submission endpoint. Decide how repeated submissions behave, when a submitted attempt becomes immutable, and what data the student may read before and after the exam closes. Explain these business rules before choosing a URL.