How to Structure a REST API: Best Practices for Backend Developers

What Is a REST API?

REST (Representational State Transfer) is an architectural style for designing networked applications. A REST API uses HTTP requests to perform operations on resources. Resources are identified by URLs, and operations are defined by HTTP methods: GET, POST, PUT, PATCH, and DELETE.

Resource Naming Conventions

Resources should be nouns, not verbs. The HTTP method defines the action.

Correct:

• GET /users — list users
• POST /users — create a user
• GET /users/42 — get a specific user
• PUT /users/42 — replace a user record
• PATCH /users/42 — update specific fields of a user
• DELETE /users/42 — delete a user

Avoid:

• GET /getUsers
• POST /createUser

HTTP Status Codes

Return appropriate status codes in every response:

Authentication

Most APIs use one of these authentication mechanisms:

Bearer Token (JWT): The client includes a signed token in the Authorization header. The server validates the token without a database lookup.

API Keys: The client includes a secret key in the header. Useful for server-to-server integrations.

OAuth 2.0: For delegated access. More complex to implement but standard for public APIs.

API Versioning

APIs change over time. Versioning prevents breaking existing integrations.

URL versioning is the most common approach:

• https://api.example.com/v1/users
• https://api.example.com/v2/users

Pagination

Return paginated results for list endpoints:

jsonCopy
{
  "data": [],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 340,
    "nextCursor": "eyJpZCI6MTAwfQ"
  }
}

Cursor-based pagination is preferable to offset pagination for large datasets.

Documentation

Use OpenAPI (Swagger) to define your API schema. Tools like Swagger UI or Scalar can generate interactive documentation from the schema automatically.

Summary

A well-structured REST API uses noun-based resource URLs, standard HTTP methods, appropriate status codes, consistent JSON response formats, versioning, and clear documentation.