REST API

Tags:

What Is REST?

REST stands for Representational State Transfer. It is an architectural style for distributed hypermedia systems such as the World Wide Web. Roy Fielding introduced REST in his 2000 doctoral dissertation. Systems that follow REST principles are often described as RESTful.

REST API

REST Characteristics

  1. Uniform interface: Resources are manipulated through a consistent and limited interface identified by URIs. An HTTP API is not tied to a specific platform or programming language.
  2. Statelessness: Each request contains the information needed to process it. The server does not need to maintain client session state between requests.
  3. Cacheability: REST uses HTTP infrastructure and can benefit from caching through headers such as Last-Modified and ETag.
  4. Client-server architecture: Clients and servers have distinct responsibilities, reducing dependencies between them.
  5. Self-descriptive messages: A request or response should contain enough information to explain how it must be processed.
  6. Layered system: Security, load balancing, encryption, proxies, and gateways can be introduced as intermediate layers.
  7. Code on demand (optional): A server may extend client behavior by sending executable logic such as JavaScript.

REST Components

Resource

A resource is an identifiable entity stored by the server. Clients request or modify its state through a URI such as /groups/{groupId}/users/{userId}. Resource names are usually nouns such as users or groups.

Method

An HTTP method expresses the action to perform on a resource. Common methods include GET, POST, PUT, and DELETE.

Representation

A representation is the form of a resource sent in a response. A resource may be represented as JSON, XML, text, or another media type.

HTTP Methods

REST APIs commonly map HTTP methods to CRUD operations.

HTTP method CRUD Collection, such as /customers Item, such as /customers/{id}
POST Create 201 Created, usually with a Location header 404 Not Found or 409 Conflict if the resource already exists
GET Read 200 OK, returning a list with pagination, sorting, or filtering as needed 200 OK, or 404 Not Found for an unknown ID
PUT Update or replace Usually 405 Method Not Allowed 200 OK or 204 No Content, or 404 Not Found
DELETE Delete Usually 405 Method Not Allowed 200 OK, or 404 Not Found

Resource Naming

Two core rules guide REST resource naming:

  • A URI represents a resource.
  • An HTTP method represents the action on that resource.

Use Nouns for Resources

Do not encode actions such as update in the URI.

GET /users/update/1  (X)
PUT /users/1         (O)

Prefer Plural Resource Names

Use plural nouns consistently for URI path segments.

GET /user/329   (X)
GET /users/329  (O)

Do Not Include File Extensions

Use an HTTP header such as Accept to request a representation.

GET /users/345/profile.jpg                          (X)
GET /users/345/profile
Accept: image/jpeg                                  (O)

Use Slashes for Hierarchy

Use / to express hierarchy, but avoid a trailing slash.

/users/{userId}/books/  (X)
/users/{userId}/books   (O)

Express Relationships Between Resources

Subresources can describe relationships.

/users/{userId}/friends
/users/{userId}/books
/users/{userId}/recommendations/books

Prefer Lowercase Paths

URI paths are case-sensitive outside the scheme and host. Lowercase paths avoid ambiguity.

/Users/{userId}/Books  (X)
/users/{userId}/books  (O)

HTTP Status Codes

A well-designed REST API returns meaningful HTTP status codes.

2xx Success

Code Meaning
200 OK The request was processed successfully.
201 Created A new resource was created successfully.
204 No Content The request succeeded and no response body is needed.

3xx Redirection

Code Meaning
304 Not Modified The requested resource has not changed since the client’s cached version.

4xx Client Error

Code Meaning
400 Bad Request The server could not understand the request syntax.
401 Unauthorized Authentication is required or failed.
403 Forbidden The server understood the request but refuses access.
404 Not Found The requested resource does not exist.

5xx Server Error

Code Meaning
500 Internal Server Error The server encountered an error while processing the request.

References