Although it may be possible that no two developers have ever had exact agreement on what a REST API is, or what it truly means to be RESTful, we would like to introduce some common vocabulary for this document:
Resource: an
abstract entity that can be addressed with
a URI and
has a unique identifier. For example, the URI https://api.example.io/v1/widgets/123 refers
to a widget resource.
Collection Resource: a resource that is (or contains) a set of other
resources. For example, the URI https://api.example.io/v1/widgets refers to a
collection resource, and we can expect that appending another path
component (e.g. /123) to the URI would identify a single element of
the collection.
Sub-resource: a resource that is scoped within another resource. For
example, the URI https://api.example.io/v1/widgets/123/components refers
to the components of a widget.
Representation: a concrete serialization of a resource, that can be
distinguished by possible other representations of the same resource by
its media type.
For example, a JSON representation for our hypothetical widget resource
would have the media type application/json.