REST API Methods List & Best Practices

REST API Design: A Comprehensive Guide

REST (Representational State Transfer) is an architectural style for designing networked applications. RESTful APIs have become the standard for web services, powering everything from mobile apps to microservices architectures. A well-designed REST API is intuitive, consistent, and enables developers to be productive without extensive documentation. This guide covers the principles and patterns that distinguish excellent APIs from mediocre ones.

While REST is not a formal specification, the industry has developed strong conventions around what constitutes a RESTful API. Following these conventions makes your API feel familiar to developers, reduces the learning curve, and enables tools and libraries to work with your API automatically.

Resource-Oriented Design

REST APIs are organized around resources—the nouns of your domain. A user, an order, a product, an article—these are resources. Each resource has a unique identifier expressed as a URL. The key insight of REST is that you operate on resources using standard HTTP methods rather than encoding actions into URLs.

Use plural nouns for collection endpoints: /users, /products, /orders. This creates a consistent pattern where /users returns a list and /users/123 returns a single item. Avoid verb-based endpoints like /getUsers or /createUser—the HTTP method expresses the action.

Resources can be nested to express relationships: /users/123/orders returns orders belonging to user 123. However, deep nesting becomes unwieldy: /users/123/orders/456/items/789/reviews is hard to work with. Beyond two levels, consider flattening: /items/789/reviews or using query parameters.

HTTP Methods as Actions

HTTP methods map naturally to CRUD operations. GET retrieves resources (read), POST creates new resources (create), PUT replaces resources entirely (update), PATCH modifies resources partially (update), and DELETE removes resources (delete). This mapping is so fundamental that REST APIs are sometimes called CRUD APIs.

The distinction between PUT and PATCH matters. PUT semantics require sending the complete resource—any field not included is set to null or default. PATCH sends only the fields being modified—unmentioned fields are preserved. PATCH is more bandwidth-efficient and avoids the risk of accidentally clearing fields.

For operations that do not fit CRUD—like "approve order" or "reset password"—use sub-resources or actions endpoints: POST /orders/123/approve or POST /users/123/password-reset. This keeps URLs noun-based while accommodating business operations.

Status Codes Communicate Outcomes

HTTP status codes are your first line of communication with clients. Use them correctly. 200 OK for successful requests with response bodies. 201 Created after successfully creating a resource (include Location header). 204 No Content for successful requests with no body (like DELETE). 400 Bad Request for validation errors. 401 Unauthorized for missing/invalid authentication. 403 Forbidden when authenticated but not authorized. 404 Not Found when a resource does not exist. 500 Internal Server Error for unexpected server failures.

Do not use 200 OK with an error message in the body—that breaks clients that check status codes. Reserve 5xx codes for actual server errors, not business logic failures. A request to delete a non-existent resource might return 404 (not found) rather than 500 (server error).

Pagination, Filtering, and Sorting

Collection endpoints must handle potentially large datasets. Pagination protects both server and client from overwhelming data volumes. Common approaches include offset-based (?page=2&per_page=20), cursor-based (?cursor=abc123&limit=20), and keyset-based (?after_id=123&limit=20). Cursor and keyset pagination perform better on large datasets.

Include pagination metadata in responses: total count, current page, per page, next/previous links. The Link header or a meta object in JSON are common patterns. Clients should not have to calculate pagination logic themselves.

Filtering narrows results: ?status=active&created_after=2024-01-01. Sorting controls order: ?sort=created_at&order=desc or ?sort=-created_at (prefix minus for descending). Field selection reduces payload size: ?fields=id,name,email returns only specified fields.

Request and Response Design

Use JSON for request and response bodies—it has become the universal format. Set appropriate Content-Type (application/json) and Accept headers. For binary data like file uploads, use multipart/form-data.

Design consistent response structures. Wrap resources in a data key: { data: { id: 1, name: "John" } }. Include metadata like pagination info. Return errors with consistent structure: { error: { code: "VALIDATION_ERROR", message: "Email is required", details: [...] } }.

Consider using JSON:API, HAL, or another hypermedia format for complex APIs. These standards define structure for resources, relationships, links, and errors, making your API self-documenting and enabling automatic client generation.

Versioning Strategies

APIs evolve. Versioning allows changes without breaking existing clients. Common strategies include URL versioning (/v1/users, /v2/users), header versioning (Accept: application/vnd.api.v1+json), and query parameter versioning (?version=1).

URL versioning is most visible and easiest for developers to understand. Header versioning keeps URLs cleaner but is harder to explore in a browser. Whatever you choose, be consistent and plan for how you will deprecate old versions.

Design for backward compatibility when possible. Adding new fields rarely breaks clients. Avoid removing fields or changing type/meaning. When breaking changes are necessary, communicate the deprecation timeline and provide migration guides.

Authentication and Security

Most APIs require authentication. Common approaches include API keys (simple but limited), OAuth 2.0 (industry standard for third-party access), and JWT (JSON Web Tokens for stateless authentication). Choose based on your security requirements and use case.

Always use HTTPS—unencrypted HTTP exposes credentials and data. Validate and sanitize all input to prevent injection attacks. Implement rate limiting to prevent abuse. Use appropriate CORS headers for browser-based access.

Follow the principle of least privilege: tokens should have only the permissions they need. Short-lived tokens with refresh capability are more secure than long-lived tokens. Log authentication failures for security monitoring.

Documentation and Developer Experience

Great documentation makes or breaks an API. Use OpenAPI (Swagger) to describe your API in a machine-readable format. Generate interactive documentation from the spec. Include request/response examples, error scenarios, and authentication details.

Provide SDKs or client libraries for popular languages. A well-designed SDK abstracts HTTP details and handles authentication, retries, and error handling. Developers can be productive faster without implementing low-level HTTP logic.

Invest in error messages. Instead of "Bad Request", explain what was wrong: "Email must be a valid email address" or "Price must be greater than 0". Include error codes that developers can use for programmatic handling.

Performance Considerations

Enable caching with appropriate headers: Cache-Control, ETag, Last-Modified. Immutable resources can be cached indefinitely. Dynamic resources need careful cache strategies with validation.

Consider response compression (gzip) for large payloads. Implement conditional requests (If-None-Match, If-Modified-Since) so clients can avoid downloading unchanged data.

For complex data requirements, consider GraphQL as an alternative or complement to REST. GraphQL excels when clients need to fetch related data in a single request, avoiding the N+1 problem of REST.