Resource Types

We in generall support the following resource types:

• List - Represents a list of entities, such as a list or products.
• Entity - Represents a single entity, such as a product.
• Processor - Represents an agent that can process a request and return the response but does not store any data. This is not REST style but required sometimes.

The meaning of the HTTP methods for the different resource types is as follows:

You can find a detailed description for the methods described for the different resource types below.

List

Represents a list of entities, such as a list or products.

Lists always support:

• OPTIONS.

Lists may support:

• GET or
• POST.

OPTIONS

GET

Retrieve list of entities.

fullData - Granularity

In general, we support two kinds of data granularity:

• Reference - The list only contains references to the actual entities.
• Full Data - The list contains the full entity data.

You can provide a fullData parameter to define the desired data granularity. Thereby, true means full data and false means references. The URL would look as follows:

Full Data - http://api.spreadshirt.net/v1/shops/42/designs?fullData=true

Default Value: In case no parameter fullData is provided, the default value false is assumed which means that only references and no full data is returned.

offset and limit - Paging

In general, you can retrieve a certain section of a list, e.g. all entities from index 20..30, by providing a limit and offset parameter. This allows you to browse through a list of designs for example without fetching all entities at once. You can use the offset and limit parameter in your search query for paging. An example query would look as follows:

Items 20..30 - http://api.spreadshirt.net/v1/shops/42/designs?offset=20&limit=30

Default Values: - In case no parameter offset or limit is provided, the default offset value 0 and limit value 1000 is used.

query - Filtering

For our article and design marketplace on eu and na platform, it is possible to return a list of entities based on given filter criteria, e.g. you want all green, yellow or red articles of size M in a specific shop. To express your search filter on a list of designs, you need to support the query parameter, for example as follows:

http://api.spreadshirt.net/v1/shops/205909/designs?query=bike +categoryIds:(1000001)

Which search attributes are actually supported by a resource depends on the actual resource.

List query calls are always GET calls to allow caching of returned search results!

sortField and sortOrder - Sorting

In case you searched on a list using a search query, you are also able to sort the returned result by a defined search index field. Therefore, you can use the sortField and sortOrder query parameters.

Valid values for sortField parameter are basically score (based on search result score or entry), weight (aka popularity), price and created.

Valid values for sortOrder parameter are basically asc (ascending order) and desc (descending order).

An example URL using these parameters would look as follows:

http://api.spreadshirt.net/v1/shops/205909/designs?query=herz&sortField=score&sortOrder=asc

showFacets - Return search facets with search result

In case you want the API search to return the possible search facets and the entry counts per facet to you, you need to turn on these facets by providing the showFacets query parameter.

Valid values are true or false.

An example URL would look as follows:

http://api.spreadshirt.net/v1/shops/205909/designs?query=herz&showFacets=true

spellcheck - Spellchecking of search queries

In case you want the API search to return a corrected search query in case no entries can be found for your search query, you need to turn spellcheck on by providing the spellcheck query parameter. 

Valid values are true or false.

An example URL would look as follows:

http://api.spreadshirt.net/v1/shops/205909/designs?query=herz&spellcheck=true

POST

Add new entity to list.

Entity

Represents a single entity, such as a product.

Entities always support:

• OPTIONS.

Entities may support:

• GET,
• PUT or
• DELETE.

OPTIONS

GET

Retrieve entity.

PUT

Update content of entity (replace not merge -> idempotent) .

DELETE

Deletes and entity and removes it from the list.

Processor

Represents an agent that can process a request and return the response but does not store any data, such as /users/123/productPriceCalculator. A processor is in our case idempotent.

Processors always support:

• OPTIONS and
• POST.

OPTIONS

POST

Process request and return response.