REST API Design

REST API design is about predictable contracts. Clients should be able to guess how to list, create, update, and delete resources because your API follows the same vocabulary throughout the product.

Resource First URLs

Start from nouns, not actions.

GET    /api/projects
POST   /api/projects
GET    /api/projects/p_123
PATCH  /api/projects/p_123
DELETE /api/projects/p_123

When an operation is not simple CRUD, model it as a sub-resource or state transition.

POST /api/projects/p_123/archive
POST /api/invoices/i_456/payments

Status Codes and Error Shapes

type ApiError = {
  error: {
    code: string;
    message: string;
    fields?: Record<string, string>;
  };
};

const invalidProjectName: ApiError = {
  error: {
    code: "project_name_required",
    message: "Project name is required.",
    fields: { name: "Enter a project name." },
  },
};

Use 400 for malformed requests, 401 for unauthenticated clients, 403 for authenticated clients without permission, 404 for missing resources, and 422 when the request is syntactically valid but violates domain rules.

NOTE

A consistent error shape matters more than a clever one. Frontends can build reusable form and toast behavior when every endpoint reports errors the same way.

Collections

Large collections need pagination, sorting, and filters that can evolve.

GET /api/tasks?status=open&limit=25&cursor=eyJpZCI6...

Cursor pagination is usually better than page numbers for frequently changing data because it is stable when rows are inserted or removed.

TIP

Include the next cursor in the response body. The client should not need to construct cursors itself.

Further Learning

Search these terms to go deeper:

“REST API resource naming conventions” — practical URL design examples
“HTTP status codes API errors” — mapping failures to status codes
“cursor pagination explained” — stable pagination for changing datasets
“API versioning best practices” — evolving contracts over time

REST API Design

A well-designed API is predictable — once you learn the pattern for one endpoint, you can guess the rest. REST is the most common convention for this: name things (nouns) as URLs, and use HTTP verbs to say what you want to do to them.

Name things, don’t verb things

GET    /api/projects          → list all
POST   /api/projects          → create one
GET    /api/projects/p_123    → get one
PATCH  /api/projects/p_123    → update one
DELETE /api/projects/p_123    → delete one

Notice the URL is always a noun (/projects), and the HTTP method carries the action. Avoid URLs like /getProject or /deleteProject — the verb belongs in the method, not the path.

For actions that aren’t simple CRUD, model them as a sub-action:

POST /api/projects/p_123/archive

Consistent errors

Every endpoint should report failures the same way, so the frontend can handle them generically:

{
  error: {
    code: 'project_name_required',
    message: 'Project name is required.'
  }
}

Use the right status code for the situation: 400 (bad request), 401 (not logged in), 403 (logged in but not allowed), 404 (doesn’t exist), 422 (looks fine but violates a rule).

Handling long lists

Big collections need paging. Ask for a page and return a “cursor” (a marker) for the next one:

GET /api/tasks?status=open&limit=25&cursor=eyJpZCI6...

TIP

Have the server give you the “next page” cursor in the response — the client shouldn’t have to construct it.

In one sentence

Design REST APIs around nouns (resources) with HTTP verbs carrying the action, return consistent, structured error shapes, use the right status codes, and support pagination for big lists.

Want to go deeper?

Switch to Expert mode above for cursor vs. offset pagination trade-offs and API versioning strategies.