Design a REST API for a Learning Platform, End to End

Model resources from the domain

Start with the nouns users and clients care about: courses, lessons, learners, enrolments and progress records. Each becomes a resource with a stable identifier. Relationships appear as nested paths only where the child cannot exist without the parent, such as /courses/{courseId}/lessons. Enrolments link learners and courses, so they work well as their own resource at /enrolments, filterable by learner or course.

Use methods and status codes consistently

• GET reads and never changes data; it can be cached and retried safely.
• POST creates a resource and returns 201 Created with a Location header pointing to it.
• PATCH updates part of a resource; PUT replaces it entirely. Pick one style per resource and document it.
• DELETE removes or archives a resource and returns 204 No Content.
• Return 400 for invalid input, 401 when authentication is missing, 403 when the user lacks permission, 404 when a resource does not exist, 409 for conflicts such as duplicate enrolment and 429 when rate-limited.

Design responses for the client

Return the fields the client needs with consistent naming, such as camelCase or snake_case throughout. Use ISO 8601 timestamps in UTC and explicit units, such as priceInPaise or durationMinutes, so values cannot be misread. Avoid exposing internal database columns that the client does not use; every exposed field becomes something you must support.

Paginate every list

Lists grow, so paginate from the start. Cursor-based pagination, where the response includes a nextCursor value the client sends back, stays correct when items are added or removed during browsing. Offset pagination is simpler and acceptable for small, slowly changing lists. Set a default and maximum page size and document both.

GET /courses?level=beginner&limit=20&cursor=eyJpZCI6IjEyMyJ9

{
  "items": [ ... ],
  "nextCursor": "eyJpZCI6IjE0MyJ9"
}

Return errors clients can act on

Use one error format across the API, including a machine-readable code, a human-readable message and field-level details for validation errors. The Problem Details format defined in RFC 9457 is a widely supported standard for this. Include a request ID in every response and in logs so support can connect a user's report to server records.

Make writes safe to retry

Mobile networks drop connections, so clients retry. For operations such as creating an enrolment or payment, accept an idempotency key header and store the result for that key; a repeated request returns the original result instead of creating a duplicate. Back it with a unique database constraint for rules such as one active enrolment per learner per course.

Authenticate and authorise every request

Authenticate with sessions for browser clients or short-lived tokens for other clients, over HTTPS only. Then authorise each request against the specific resource: a learner may read their own progress but not another learner's, even if they guess the ID. Write tests for these rules, because missing object-level authorisation is one of the most common API vulnerabilities.

Version and document

Avoid breaking changes: add fields rather than renaming them, and keep old behaviour until clients migrate. When a breaking change is unavoidable, introduce a new version and announce a deprecation timeline. Describe the API in an OpenAPI document with an example request and response for every operation, and test that the examples actually work.

Checklist

• Resources and identifiers reflect the domain
• Methods and status codes are used consistently
• Every list is paginated with limits
• Errors share one format and include a request ID
• Create operations accept idempotency keys
• Every request is authorised against the specific resource
• An OpenAPI document with tested examples is maintained