Resource Types supported by Spreadshirt API v1

As described in Spreadshirt API v1 Explained, the Spreadshirt Data and Image API is provided as a RESTful (Representational State Transfer) API via HTTP, which means that we use HTTP methods, HTTP status codes, URL structures and the concepts of resource and representation correctly to allow API clients to retrieve, create, update and delete data and images.

The Wikipedia article about REST (Representational State Transfer) describes the REST-style architecture and the concept of resource and representation as follows: “REST-style architectures consist of clients and servers. Clients initiate requests to servers; servers process requests and return appropriate responses. Requests and responses are built around the transfer of representations of resources. A resource can be essentially any coherent and meaningful concept that may be addressed. A representation of a resource is typically a document that captures the current or intended state of a resource.” The section on RESTful web services in the Wikipedia article also describes the proposed URL structures and usage of HTTP methods for what is called collections and elements in the article.

Resource Types

Based on that description, we define that the Spreadshirt Data and Image basically provide two resource types, that we call list and entity.

  • List: A resource of type list basically allows to retrieve URLs of the entities in the list or even a partial or full representations of the entities in the list. It also allows to add members to the list.
    An example for a list resource is the products resource on the Spreadshirt Data API which returns a list of URIs to the actual product entities in the list. Using the fullData query parameter and setting it to true, one can also retrieve a list with the full product entity representations.
  • Entity: A resource of type entity allows to retrieve a representation of the entity, replace the current entity representation with a new one, or delete the entity from the list.
    An example for an entity resource is the product resource on the Spreadshirt Data API which returns the representation of a product entity.

However, in some situations, the two resource types list and entity – that correspond to the definition of RESTful web services – are not enough and we need a third resource type, that we call processor.

  • Processor: A resource of type processor basically receives a request representation, does some processing of the request representation and returns the processing result as a response representation.
    An example for such a processor resource would be a product price calculator for non existing products, where you send the product representation with the request to the processor and retrieve the calculated product price as a representation in the response.

URL Structure

Knowing the basics, I now want to explain the details starting with the URL structures for the different resource types. You can see an overview of the supported URL structures below:

Resource Type URL Structure Example
List Last segment of the URI is a noun in plural form that describes what is in the list, e.g. products. …/api/v1/shops/205909/products
Entity Last segment of the URI is usually the identifier (id) of the entity, with which it can be addressed, e.g. 23945182. The next to last element is again the noun in plural form that describes what is in the list, e.g. products. …/api/v1/shops/205909/products/23945182
Processor Last segment of the URI is a noun in singular form that describes what the processor does, e.g. productPriceCalculator. …/api/v1/shops/205909/productPriceCalculator

HTTP Methods

Having introduced the supported URL structures, I now want to explain the supported HTTP methods for the different resource types. An overview is illustrated in the table below:

Resource Type\ HTTP Method GET PUT POST DELETE OPTIONS
List Retrieve list of entities. Create a new entity in the list and assign an ID automatically. Return ID in response. Return resource description.
Entity Retrieve a representation of the addressed entity of the list. Update addressed entity of the list. Delete addressed entity of the list. Return resource description.
Processor Process request and return response. Return resource description.

One can see, that the list resource type supports the HTTP methods GET and POST for retrieving a list of entities or adding a new entity to the list.
The resource type entity supports HTTP methods GET, PUT, DELETE to retrieve, update and delete an entity.
The resource type processor supports HTTP method POST to process a request and return a response.
All resource types support HTTP method OPTIONS, which returns a description of the supported HTTP methods, HTTP status codes and request and response representations.
Please note that HTTP methods PUT and DELETE are idempotent and GET is safe.

HTTP Status Codes

In the table below, you can see the most important HTTP status codes that must be understood when working with the API.

Resource Type\ HTTP Method GET PUT POST DELETE OPTIONS
List 200 – OK
400 – Bad request
500 – Internal error
201 – Created
400 – Bad request
500 – Internal error
200 – OK
500 – Internal error
Entity 200 – OK
400 – Bad request
404 – Resource not found
500 – Internal error
200 – Replaced
400 – Bad request
404 – Resource not found
500 – Internal error
200 – Deleted
400 – Bad Request
404 – Resource not found
500 – Internal error
200 – OK
500 – Internal error
Processor 200 – Processed
400 – Bad Request
500 – Internal error
200 – OK
500 – Internal error

As you can see, in most cases the API will return HTTP status code 200 for successful operations. There is one exception to the rule, the POST on a resource of type list. In this case, the API will return HTTP status code 201, which indicates that a new entity has been created. The response also contains a
Location header that contains the URL with which the newly created entity can be addressed.
The API will return HTTP status code 404 for resources of type entity in all those cases where the entity to be accessed actually does not exist.
The API will return HTTP status code 400 in all those cases, where request data is broken somehow, either because data extracted from query parameters is broken or because the data from the request representation is broken somehow.
HTTP status code 500 will be returned in all those cases, where other server-side errors occurred.

Conclusion

In this blog post, I described the three resource types list, entity and processor, that we use to classify the resources provided by Spreadshirt’s Data and Image API. I also explained the URL structure, HTTP methods and HTTP status codes supported for each resource type. With this knowledge, it should be easier for you to work with the resources provided by Spreadshirt’s Data and Image API and to build client applications that make use of the provided data and functionality. In our developer wiki, we describe the resource types and the resources provided by Spreadshirt’s Data and Image API in depth.