Each service provided by the API is an archetype, and they indicate the structures and behaviors of REST API designs. Resource modelling should start with a few fundamental resource archetypes, and usually, the REST API is composed of four unique archetypes, as follows:
- Document: The document is the base for a resource representation with a field and link-based structure. In the following, each sample URI represents unique document resources, and the first one is also called the doc-root or parent resource ( the API endpoint):
- Collection: A collection is also a resource, and it is a directory of resources managed by the API providers or servers. If a collection allows creating a new resource, then the clients can add new resources to the collections. A collection resource decides the URIs of each contained or added resources. In the following, each URI sample found identifies a collection resource:
- Stores: A store is a resource repository managed by the client. The store allows the API client to put resources in, choose URIs for the resources that get added, get them out, and delete them when it decides. (URI stores never generate a new URI, and it is the client who chooses when resources initially get added.) Some of the following examples of interaction show a user of a client program of a cart- and song-management API inserting a document resource named carts and playlists respectively against his/her user ID denoted by {id}:
- Controller: Controller resources are similar to executable methods, with parameters and return values. REST API relies on controller resources to perform application-specific actions that do not come under any of the CRUD methods. Controller names should always appear as the last segment in a URI path, with no child resources to follow them in the hierarchy:
- POST /alerts/245245/resend is an example of a controller resource that allows a client to resend an alert to a user