Architecture and Protocol

Resources and collections

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on.

- Roy Thomas Fielding, "Architectural Styles and the Design of Network-based Software Architectures"

In Puro REST Framework we use two different key concepts, Resources and Collections of resources, to help us to distinguish which actions we can perform on single objects and which ones on list of objects:

Action	HTTP Method	Target	Description
create	POST	Collection	Creates a new resource.
read	GET	Resource / Collection	Reads a single resource or a collection of resources.
update	UPDATE	Resource	Updates a resource.
delete	DELETE	Resource / Collection	Deletes a resource or a collections of resources.

Finally, for simplicity, we call Property a resource which is contained inside another resource rather than a collection.

URIs

The URI (Uniform Resource Identifier) is a string of characters that unambiguously identifies a particular resource or collections of resources.

For example, the following URI points to a resource called "title", contained inside another resource with identifier "25" and part of a collections called "books":

https://api.domain.com/v1/books/25/title

If the URI has been well designed we can get the URI to the collection "books" by truncating its path:

https://api.domain.com/v1/books

It's good practice to use singular nouns to identify single resources and plural nouns to identify collections of resources.

HTTP requests

TODO

HTTP methods

TODO

The request-response cycle