Mobile REST API design: endpoints, errors, pagination and versioning

Who is this for?

Developers building Node.js, Laravel or Python mobile backends.

Before you start

An example data model, roles and an owned staging API.

1. Define resources and permissions

An endpoint is not simply a table wrapper. For /projects/{id}/notes, the project identifier does not establish permission. Derive the user from the session and check membership on the server. A client-submitted owner field cannot replace this boundary.

2. Bound list responses

Return fields needed by the screen. Use deterministic ordering and a unique tie-breaker, with a server-side maximum page size. Offset can suit small datasets; cursors can better serve large, changing lists.

GET /v1/notes?limit=20&after=opaque-cursor
{ "items": [{ "id": "note-42", "title": "Draft" }],
  "next_cursor": "opaque-next", "has_more": true }

3. Publish stable errors

Clients should not parse translated prose to decide recovery. Return a stable code, HTTP status and safe explanation. Keep stack traces, SQL and credentials out of responses. A request identifier can connect a client error to protected server logs.

4. Make repeated writes safe

A timeout can follow a committed write. Retain the same idempotency key for a logical operation and bind it to user, operation and payload. Reject incompatible key reuse. Reading a resource and creating a payment must not share an indiscriminate retry rule.

5. Support old mobile releases

Devices do not update simultaneously. Adding an optional field differs from removing or retyping one. Keep older client fixtures in contract tests. Represent timestamps explicitly and money using currency and minor units. Plan breaking changes with a migration window.

6. Verify the boundary

These endpoints are design examples for your API, not live Uygulama Cloud customer endpoints. Test missing sessions, cross-user identifiers, invalid cursors, excessive limits and repeated writes. Compare OpenAPI with actual responses.

• Bound timeout and payload size.
• Enforce tenant ownership on every action.
• Avoid secrets and personal data in errors.
• Require backward-compatibility tests before release.