As explained before, the Spreadshirt API is implemented as a REST API. In order to better understand the following API documentation, we now explain what REST in the context of our API means.
In our understanding, REST consists of the following concepts:
- Resource: Anything a client might want to link to. Or in other words a thing that can be stored on a computer and represented as a stream of bits, e.g. document, database row, result of running an algorithm. Each resource has state.
- Resource Identifier: A resource identifier or resource name is used to identify a resource. A resource may have one or many URIs.
- Representation: Data about current state of the resource that can be accessed or modified via the URI. Different variants might exist, e.g. for different languages, content types, etc..
- Links: Each representation includes enough information to describe how to process the representation, for example which parser to invoke, and how it is connected to other representations.
For us, REST also has the following properties:
- Addressability: An application exposes a URI for every piece of information it might serve, URIs can be reused and always deliver a similar result (state might change). URIs can be bookmarked.
- Statelessness: Every HTTP request happens in complete isolation. There is no client-specific server state. However, a client can have different application states during a conversation with the server. Through that characteristics, client requests can easily be load balanced to and responses can be cached.
- Connectedness/ Hypermedia: Resources are linked to each other in their representations („Hypermedia as the engine of application state“).
- Uniform Interface: Fixed set of methods that can be executed on resource (not only POST as with Web services). Method invocation might modify resource state.
REST over HTTP
REST is in general not bound to any specific protocol. However, we use REST based on the HTTP protocol as most people do. The REST concepts map to the HTTP concepts as follows:
List of Products
Resource Identifier -> HTTP URI
Uniform Interface -> HTTP method + status code
Representation -> XML payload