Skip to content

RESTful resource representation

In RESTful architecture, every resource is represented by a specific URI (Uniform Resource Identifier).^[600-developer__principle__restful-rule.md]

URI Structure

URIs must contain only nouns and avoid verbs, as the URI identifies the entity itself rather than the action performed on it^[600-developer__principle__restful-rule.md]. Nouns used in the API typically correspond to database table names and should generally be in plural form to represent a "collection" of records^[600-developer__principle__restful-rule.md].

A common design error is including verbs in the path (e.g., /transfer); actions should be conveyed solely through the HTTP method instead^[600-developer__principle__restful-rule.md].

Representation and State

The interaction between the client and server involves transferring a representation of the resource^[600-developer__principle__restful-rule.md]. Clients use four HTTP verbs to manipulate these representations, thereby triggering "Representational State transfer" on the server^[600-developer__principle__restful-rule.md].

Return Structures

The structure of the returned data depends on the target of the request:

  • List: GET /collection returns a list (array) of resource objects^[600-developer__principle__restful-rule.md].
  • Single Object: GET /collection/resource returns a single resource object^[600-developer__principle__restful-rule.md].
  • Creation: POST /collection returns the newly generated resource object^[600-developer__principle__restful-rule.md].
  • Updates: PUT or PATCH returns the modified, complete resource object^[600-developer__principle__restful-rule.md].
  • Deletion: DELETE returns an empty document^[600-developer__principle__restful-rule.md].

Sources