What is a REST API?

A REST API (Representational State Transfer Application Programming Interface) is an architectural style for web services that uses standard HTTP methods and URLs to perform operations on resources. REST is the dominant pattern for building web APIs.

Core principles

REST was defined by Roy Fielding in his 2000 doctoral dissertation. The key constraints:

• Client-server separation: The client and server are independent. The client doesn’t need to know about data storage; the server doesn’t need to know about the UI.
• Statelessness: Each request contains all the information needed to process it. The server doesn’t store client session state between requests.
• Uniform interface: Resources are identified by URLs. Operations use standard HTTP methods. Responses are self-descriptive.
• Cacheability: Responses should indicate whether they can be cached.

Resources and HTTP methods

In REST, everything is a resource identified by a URL. Standard HTTP methods map to CRUD operations:

GET    /api/users        → List all users
GET    /api/users/42     → Get user 42
POST   /api/users        → Create a new user
PUT    /api/users/42     → Replace user 42
PATCH  /api/users/42     → Partially update user 42
DELETE /api/users/42     → Delete user 42

The URL structure is noun-based (resources), not verb-based. /api/getUser is not RESTful; GET /api/users/42 is.

Request and response format

REST APIs typically use JSON for request and response bodies. The Content-Type: application/json header indicates the format. Responses include appropriate HTTP status codes: 200 for success, 201 for creation, 404 for not found, 422 for validation errors.

POST /api/users
Content-Type: application/json

{
  "name": "Ada Lovelace",
  "email": "ada@example.com"
}

HTTP/1.1 201 Created
Location: /api/users/42

Authentication

Common patterns for REST API authentication:

• API keys: Sent in a header or query parameter. Simple but limited.
• Bearer tokens (JWT): Sent in the Authorization: Bearer <token> header. Stateless and scalable.
• OAuth 2.0: Delegated authorization for third-party access.

REST vs. GraphQL

REST returns fixed data shapes — each endpoint returns a predetermined structure. GraphQL lets clients specify exactly which fields they need, reducing over-fetching. REST is simpler and benefits from HTTP caching; GraphQL is more flexible for complex data requirements.

Best practices

• Use plural nouns for resource URLs (/users, not /user)
• Version your API (/api/v1/users)
• Use proper status codes (not just 200 for everything)
• Support pagination for list endpoints
• Return meaningful error messages with consistent structure

Test API responses with the API Response Viewer, format JSON payloads with the JSON Formatter, or convert curl commands to code with curl to Code.