Page tree
Skip to end of metadata
Go to start of metadata

Conventions

  • Id's are always an attribute
  • Human-readable text (e.g. name, description, ...) must be a text child of an element, not an attribute

Format

Rule

Date and Time

Date and Time values are always annotated in a ISO8601 format, see [IT:IS8601].
Example: 2008-05-15T12:59:23+02:00

Color

RGB color values are always denoted with a '#' (this is standard in SVG, and we want the whole API to be consistent).

Hypermedia

Resource are connected with each other via xlinks in their representations. That means the entities link each other and therefore are put into relationshops. A user has for exampple a set of shops and each shop has a default country assigned. This relationships are modeled in our API via xlink:hrefs. Use this xlink:hrefs to write code that is easy to maintain and does not break on URL pattern changes - which might occur but only as exceptions.

Example:

User links shops

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns="http://api.spreadshirt.net"
      xlink:href="https://api.spreadshirt.net/api/v1/users/42" id="42">
    ...
    <shops xlink:href="https://api.spreadshirt.net/api/v1/users/42/shops"/>
</user>

Shop links country

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<shops xmlns:xlink="http://www.w3.org/1999/xlink"
       xmlns="http://api.spreadshirt.net"
       sortOrder="asc" sortField="default" count="12" limit="10"
       offset="0"
       xlink:href="https://api.spreadshirt.net/api/v1/users/42/shops?fullData=true">
    <shop xlink:href="https://api.spreadshirt.net/api/v1/shops/100000" id="100000">
        ...
        <country xlink:href="https://api.spreadshirt.net/api/v1/countries/1" id="1"/>
        ...
    </shop>
   ...
</shops>

Country is

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <country xlink:href="https://api.spreadshirt.net/api/v1/countries/1" id="1">
   <isoCode>DE</isoCode>
   <thousandsSeparator>.</thousandsSeparator>
   <decimalPoint>,</decimalPoint>
   <length>
      <unit>cm</unit>
      <unitFactor>1.0</unitFactor>
   </length>
   <currency xlink:href="https://api.spreadshirt.net/api/v1/currencies/1" id="1"/>
</country>

MediaTypes

The Data API supports media type XML (application/xml) and JSON (application/json). XML is the default media type for data. You could change the media type by setting the request URL parameter mediaType and using a different value like json.

NOTESupport for JSONP (application/javascript) has been discontinued. Please use JSON instead.

The Image API supports media type PNG (image/png), JPG (image/jpg), GIF (image/gif), SWF (image/swf) as output media type formats. Default is PNG. You can change the media type as described above by using the mediaType parameter.

Common Value Types

Price

Field

Description

vatExcluded

The price without shop, user or request country specific vat, e.g. 27 €..

vatIncluded

The price with shop, user or request country specific vat, e.g. 23,50 €.

vat

The vat in percent, e.g. 19 %.

currency

The currency id, e.g. 1 for €.

Example:

...
   <price>
      <vatExcluded>19.74</vatExcluded>
      <vatIncluded>19.74</vatIncluded>
      <vat>0</vat>
      <currency xlink:href="https://api.spreadshirt.net/api/v1/currencies/1" id="1"/>
   </price>
...

Point

Field

Description

x

The x coordinate of the point, e.g. 150.

y

The y coordinate of the point, e.g. 30.

@unit

The unit of the x and y values, i.e. mm or px.

Example:

...
   <offset unit="mm">
      <x>32.4043444553484</x>
      <y>42.3750686947988</y>
   </offset>
...

Dimension

Field

Description

width

The width of the described area.

height

The height of the described area.

@unit

The unit of the x and y values, i.e. mm or px.

Example:

...
   <size unit="mm">
      <width>263.7982195845697</width>
      <height>263.7982195845697</height>
   </size>
...

Shape

Field

Description

content

The actual shape content.

content/@unit

The unit of  the positioning values, i.e. mm or px.

content/svg

The shape description as SVG. Please read SVG specification for more details.

Example:

...
   <soft>
      <content unit="mm">
         <svg>
            <path  d="M0 0 L0 588.945 L326.571 588.945 L326.571 0
                      L246.571 0 L202.25 100  L162.25 140 L122.25
                      100 L80 0 Z"/>
         </svg>
      </content>
   </soft>
...

Reference

Field

Description

@id

The resource id to which this reference points.

@href

A link to the resource to which this reference points.

Example:

...
   <currency xlink:href="https://api.spreadshirt.net/api/v1/currencies/1" id="1"/>
...

Representation Types

List

A list represents an ordered set or entities.

Field

Description

<list>

The list tag, e.g. designs, products or product types.

<list>/@xmlns:xlink

Namespace for used xlinks.

<list>/@xmlns

Standard API namespace. Don't forget to add this namespace to the entity tags when posting XML representations to our servers!

<list>/@xlink:href

The link of that list. Can be used to retrieve the list again or to point to that list somewhere else.

<list>/@offset

The position greater or equal 0 from which we wanted to retrieve entities in the list, e.g. 20.

<list>/@limit

The max possible number of entities in the retrieved list, e.g. 10.

<list>/@count

The number of entities in the list independent of specified offset and limit attributes, e.g. 53.

<list>/@sortOrder

The order by which we wanted the returned list to be sorted, e.g. ascending (asc) or descending (desc).

<list>/@sortField

The field by which we wanted the returned list to be sorted, e.g. name, dateCreated or dateModified.

<list>/@query

The query we were searching entities for that are now in the list.

<list>/@suggestedQuery

The suggested query (spell checked and corrected query) for the given request query in case spellcheck is turned on.

<list>/facets

In case the list is the result of a search (query parameter provided in request) and facets are turned on (showFacets parameter provided in request and set to true), the list also contains the different search results per search facet.

<list>/facets/facet

The entry counts for one search facet, e.g. product type departments, product type colors or article categories.

<list>/facets/facet/@type

With a facetted search one can search on different facets, i.e. by different criteria. One can search for example articles that have a product type that is in a specific product type department and that are in specific article categories. The facet will return the entry counts, i.e. found results. The type defines for which facet the entry counts are returned.

<list>/facets/facet/entryCount

The entry count tells you, how much entries were found for that facet in general.

<list>/facets/facet/optionPattern

The option pattern is an  abstract pattern that you can use to add it to your query string and further refine the search. Replace x with one or more entry ids, e.g.  +productTypeDepartmentIds:( 1) or +productTypeDepartmentIds:( 1 2 3 4).

<list>/facets/facet/entries

The entry counts found for one facet, e.g. in facet product type departments there are results for man, woman or accessoires.

<list>/facets/facet/entries/entry

The entry counts for one facet entry, e.g. man.

<list>/facets/facet/entries/entry/@id

The id of the facet entry for which entry counts were returned. Corresponds to the id of the actual entity used for constraining the search, e.g. product type department man has id 1 for which results were returned.

<list>/facets/facet/entries/entry/entryCount

The number of entities found for that facet entry, e.g. 541 entities for product type department man.

<list>/facets/facet/entries/entry/option

The option you can use to further refine your search and only search for entries that match this criteria, e.g. you searched for love in general and now want to refine your search to love  +productTypeDepartmentIds\:(1).

Example:

<articleCategories xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns="http://api.spreadshirt.net"
         sortOrder="asc" sortField="default" count="12"
         limit="10" offset="0"
         xlink:href="https://api.spreadshirt.net/api/v1/shops/42/designs?fullData=true"
         query="love" suggestedQuery="love">
        <facets>
            <facet type="PRODUCT_TYPE_DEPARTMENT">
            <entryCount>690</entryCount>
            <optionPattern>+productTypeDepartmentIds:(x)</optionPattern>
            <entries>
                <entry id="1">
                    <entryCount>541</entryCount>
                    <option>+productTypeDepartmentIds:(1)</option>
                </entry>
                ...
            </entries>
          </facet>
          ...
        </facets>
    ...
<articleCategories>

Entity

Entities represent single entities.

Field

Description

<entity>

The entity tag, e.g. design, product or productType.

<entity>/@xmlns:xlink

Namespace for used xlinks.

<entity>/@xmlns

Standard API namespace. Don't forget to add this namespace to the entity tags when posting XML representations to our servers!

<entity>/@id

The ID (identifier) of the entity.

<entity>/@xlink:href

The link of the entity. Can be used to retrieve entity again or to point to entity. For example, when putting it into the basket.

Example:

<design xmlns:xlink="http://www.w3.org/1999/xlink"
        xmlns="http://api.spreadshirt.net"
        xlink:href="https://api.spreadshirt.net/api/v1/shops/42/designs/1"
        id="1">
   ..
</design>
  • No labels