Design APIs Around Resources

Use Clear Resource Naming

APIs should represent business entities as resources with clear, meaningful names. Resource names should be easy to understand and consistent throughout the API. For example, /users, /products, and /orders clearly communicate what each endpoint represents.

Use Nouns Instead of Verbs

Use nouns to represent resources rather than action-based words. HTTP methods already describe the operation, so endpoints like/users or /orders are generally clearer than /getUsers or /createOrder.

Example:

GET /users
GET /products
GET /orders

This approach keeps endpoint structures predictable and easier for developers to work with.

Use HTTP Methods Correctly

HTTP methods communicate the intended action for a request. Using them consistently makes APIs more intuitive and helps developers understand how to interact with different resources.

GET

Use GET to retrieve resources without modifying existing data.

POST

Use POST to create a new resource or submit data for processing.

PUT

Use PUT when replacing an existing resource with a new representation.

PATCH

Use PATCH when updating specific fields or parts of an existing resource.

DELETE

Use DELETE to remove a resource.

Example:

GET    /users
POST   /users
PUT    /users/101
PATCH  /users/101
DELETE /users/101

Using HTTP methods consistently creates a predictable API structure and reduces integration confusion.

Maintain Consistent Naming Conventions

Consistency in naming makes APIs easier to understand, use, and maintain. Developers should establish naming standards before creating endpoints and apply them across the entire API.

URL and Endpoint Naming

Keep endpoint names simple and consistent. Use a common format for resources, pluralization, capitalization, and nested relationships.

/users
/users/101/orders
/products

Request and Response Field Naming

Request and response fields should also follow a consistent naming style. For example, an API can consistently use first_name and last_name or firstName and lastName rather than mixing different conventions.

Example:

{
"userId": 101,
"firstName": "John",
"lastName": "Smith"
}

A consistent naming strategy makes API responses more predictable and reduces unnecessary development effort.

Use Appropriate HTTP Status Codes

HTTP status codes give clients immediate information about whether a request succeeded or encountered an issue. Choosing the appropriate status code makes API behavior easier to understand and troubleshoot.

Successful Responses

Common success codes include:

1. 200 OK – The request was successfully processed.
2. 201 Created – A new resource was successfully created.
3. 204 No Content – The request succeeded without returning a response body.

Client Errors

Client-side issues can be represented with codes such as:

1. 400 Bad Request – The request contains invalid or missing information.
2. 401 Unauthorized – Authentication is required or invalid.
3. 403 Forbidden – The client does not have permission to access the resource.
4. 404 Not Found – The requested resource does not exist.

Server Errors

Use 500 Internal Server Error for unexpected problems occurring on the server. Use other 5xx status codes when a more specific server-side condition applies.

Example:

POST /users
→ 201 Created
GET /users/999
→ 404 Not Found

Using meaningful status codes allows consuming applications to handle responses appropriately.

Keep API Design Simple and Intuitive

An API should let developers understand its behavior without studying complicated rules. Simplicity improves usability and reduces the learning curve for developers integrating with the API.

Avoid Unnecessary Complexity

Avoid excessive parameters, deeply nested endpoints, and redundant functionality. Each endpoint should have a clear purpose and provide only the information required for the intended operation.

Maintain Predictable API Behavior

Similar operations should behave in similar ways throughout the API. Consistent request structures, response formats, and endpoint patterns make APIs easier to consume and maintain.

Example:

Instead of creating separate endpoints for every possible action, use resource-oriented endpoints with appropriate HTTP methods:

GET    /orders/101
PATCH  /orders/101
DELETE /orders/101

This keeps the API structure straightforward and easier to extend.

Design for Security

Consider security throughout the API lifecycle, not only after development. APIs often handle sensitive business and user data, making proper protection essential. Following API security practices can help protect endpoints, user data, and backend resources from common threats.

Authentication and Authorization

Use secure authentication mechanisms to verify API users or applications. Authorization should then determine which resources and operations each authenticated client can access.

Data Validation

Validate incoming data before processing it. Input validation helps prevent malformed API requests and reduces the risk of common security issues.

Rate Limiting

Rate limiting controls how many requests a client can make within a specific period. It can help protect APIs from excessive traffic, abuse, and resource exhaustion.

Example:

POST /users
Authorization: Bearer 
{
"email": "user@example.com",
"name": "John Smith"
}

Sensitive information should also be transmitted over secure connections and handled according to applicable security requirements.

Implement API Versioning

As applications evolve, APIs may need changes that could affect existing consumers. API versioning provides a structured way to introduce changes while maintaining compatibility with older integrations.

URL Versioning

Version information can be included directly in the endpoint:

/api/v1/users
/api/v2/users

This approach is simple and makes the API version immediately visible.

Header Versioning

Another approach is to specify the API version through request headers. This keeps version information out of the URL while allowing clients to request a particular API version.

Example:

GET /users
Accept: application/vnd.company.v2+json

Whichever approach you choose, apply versioning consistently and support it with a clear migration strategy.

Provide Consistent Error Handling

Well-structured error responses help developers quickly identify and resolve problems. Instead of returning different error formats across endpoints, APIs should use a standardized structure.

Standard Error Response Structure

A consistent response can include an error code, message, and additional details where appropriate.

{
"error": {
"code": "INVALID_EMAIL",
"message": "The provided email address is invalid."
}
}

Meaningful Error Messages

Error messages should explain what went wrong without exposing sensitive internal information. Clear messages help API consumers understand how to correct invalid requests.

Support Filtering, Sorting, and Pagination

APIs that return large datasets can become inefficient if they send every available record in a single response. Filtering, sorting, and pagination give clients greater control over the data they receive.

Filtering

Filtering lets clients request only records that match specific criteria.

GET /products?category=electronics

Sorting

Sorting lets clients control the order of returned results.

GET /products?sort=price

Pagination

Pagination divides large datasets into smaller, manageable responses.

GET /products?page=2&limit=20

These capabilities can reduce unnecessary data transfer and improve the overall efficiency of API interactions.

 Create Clear API Documentation

Good documentation is essential for helping developers understand how to integrate with an API. Even a technically well-designed API can be hard to use if its behavior and requirements aren’t clearly documented.

Endpoint Documentation

Document each API endpoint along with its purpose, HTTP method, URL structure, query parameters, and expected responses.

Request and Response Examples

Include practical examples showing how requests should be structured and what clients can expect in return.

{
"id": 101,
"name": "Wireless Headphones",
"price": 99.99
}

Authentication Instructions

Clearly explain the authentication method, required headers, token format, and relevant permissions. Well-maintained documentation helps developers integrate faster and reduces unnecessary support requests.

Example:

A complete endpoint reference could include:

GET /api/v1/products/{id}
Authentication: Bearer Token
Response: 200 OK
{
"id": 101,
"name": "Wireless Headphones",
"price": 99.99
}

Clear, up-to-date documentation makes an API easier to adopt, test, and maintain throughout its lifecycle.