Skip to content

Resource Representation in REST

In a RESTful architecture, resources are the fundamental abstraction of information that can be addressed and transferred.^[600-developer-principle-restful-rule.md]

Core Concepts

Every resource is identified by a unique URI (Uniform Resource Identifier).^[600-developer-principle-restful-rule.md] While the resource represents the entity itself (e.g., a user or a zoo), the representation is the specific manner in which the resource's current state is transmitted between the client and the server.^[600-developer-principle-restful-rule.md] This exchange of representations is what enables the client to manipulate the resource's state.

URI Design and Naming

A critical principle in REST is that URIs should represent resources using nouns, not verbs.^[600-developer-principle-restful-rule.md] Because resources often correspond to database tables—which are collections of records—the standard practice is to use plural nouns in the URI path.^[600-developer-principle-restful-rule.md]

  • Correct: POST /accounts/1/transaction
  • Incorrect: POST /accounts/1/transfer

This approach ensures that the URI identifies the what (the resource), while the HTTP method defines the how (the action).

Representations and HTTP methods

The client interacts with resource representations using standard HTTP verbs.^[600-developer-principle-restful-rule.md] The format of the representation returned to the client typically depends on the specific type of request made:

Method Description Response Representation
GET Retrieves a resource (one or many).^[600-developer-principle-restful-rule.md] List/Array: For collections (e.g., GET /zoos).^[600-developer-principle-restful-rule.md]
Single Object: For specific items (e.g., GET /zoos/ID).^[600-developer-principle-restful-rule.md]
POST Creates a new resource on the server.^[600-developer-principle-restful-rule.md] New Object: Returns the representation of the newly generated resource.^[600-developer-principle-restful-rule.md]
PUT Updates a resource using complete data provided by the client.^[600-developer-principle-restful-rule.md] Full Object: Returns the complete, updated resource object.^[600-developer-principle-restful-rule.md]
PATCH Updates a resource using partial data provided by the client.^[600-developer-principle-restful-rule.md] Full Object: Returns the complete, updated resource object.^[600-developer-principle-restful-rule.md]
DELETE Removes a resource from the server.^[600-developer-principle-restful-rule.md] Empty Document: Returns an empty document upon success.^[600-developer-principle-restful-rule.md]

Sources

^[600-developer-principle-restful-rule.md]