The Product Type Model (API Terminology Explained #2)

In my last blog post in the series “API Terminology Explained”, I explained the difference between product type, product and article. In this blog post, I will give you more details on our product type model.

Understanding the Product Type Model

In our terminology, a product type represents the pure piece or apparel, e.g. a T-shirt, as we get it from our supplier, e.g. American Apparel. A typical product type, e.g. a yellow T-shirt from American Apparel in size M, is illustrated in the picture above.  A product type has the following characteristics:

  • Core data: Each product type has a set of core data, such as name description and price.
  • Appearances: A product type has one or more appearances. An appearance describes a pattern/color combination for a piece of apparel, e.g. a yellow T-shirt (no pattern/yellow color) or a camouflage T-shirt (camouflage pattern/light green and dark green as colors). It’s important to understand that we are not able to print with each available print type, e.g. flock, flex or digital direct, on each available product type. Therefore, we define for each appearance, which print types are allowed.
  • Sizes: A product type has one or more sizes, such as S, M or L. Please note, that size information may vary between different product types. Sizes for adults are for example different from sizes for babys or kids.
  • StockStates: Each product type provides stock state information for all allowed appearance/size combinations. We tell you for each combination, whether we have that in stock or not.
  • Views: Views describe from which position a human being can look on a specific piece of apparel. Each product type has at least one view. The most common views are apparent: one can look on a piece of apparel from front, back, left and right. However, less apparent is that specific product types have hoods which adds two other views: hood left and hood right. Views for shirts are also different from views for trousers. And last but not least, one can also print on the inside areas of certain shirts, e.g. basketball shirts, which adds another set of possible views.
  • PrintAreas: Print areas descibe those parts on a piece of apparel on which we can actually print text and designs using different print types and print colors. Print areas are usually rectangular. However, there are cases where rectangular print area descriptions are not sufficient, for example for T-shirts with v-neck. Another issue is that there might be knobs,  pockets or zippers on a T-shirt on which we cannot print – and which we also need to describe. That’s the reason why our print area model contains a hard boundary and soft boundary description for each print area. The hard boundary describes the shape inside which one has to position ones text and designs. The soft boundary describes all things inside the hard boundary on which we can’t print, e.g. zipper.
  • ViewMaps: We use view mappings to map the defined print areas to the different views of a product type. To understand that, you need to imagine two print areas, one for the front of a T-shirt and one for the left arm. So, for the description of the front view, we could define two view maps: one that maps the print area for the front directly to the view and another one that maps the print area for the left arm to the view, such that we only see a part of the print area when looking from the front on that shirt.

Retrieving Product Type Data

Knowing how the product type model works, I will now tell you, how to retrieve the data required for creating own applications. For each product type, we provide an XML description as well as images for the different views and appearances. As described in Spreadshirt API v1 Explained, you can use the Data API to retrieve the XML descriptions and the Image API to retrieve the images.

  • XML description: To retrieve a product type XML description, you can for example use a URL similar to the following one: http://api.spreadshirt.net/api/v1/shops/40000/productTypes/175. Using that URL, you will receive an XML description similar to the one below:
    
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <productType id="175" ...>
        <appearances>
           ...
        </appearances>
        <sizes>
           ...
        </sizes>
        <views>
            <view id="1">
                ...
                <viewMaps>
                    ...
                </viewMaps>
                ...
            </view>
           ...
        </views>
        <printAreas>
          ...
        </printAreas>
        <stockStates>
          ...
        </stockStates>
        ...
    </productType>

    You can see, that the highlighted XML tags correspond to the parts of a product type described above. You can find the XML schema definition for product types in the api.xsd.

  • Images: To retrieve a product type image, you can use a URL similar to the following one: http://image.spreadshirt.net/image-server/v1/productTypes/175/views/1/appearances/135. It is important to understand, that these URLs are provided with the resources parts of the product type XML description:
    
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <productType id="175" ...>
        ...
        <appearances>
            <appearance id="1">
                ...
                <resources>
                    <resource xlink:href="http://image.spreadshirt.net/image-server/v1/productTypes/175/views/1/appearances/1" mediaType="image/png"/>
                </resources>
            </appearance>
        </appearances>
        <resources>
            <resource xlink:href="http://image.spreadshirt.net/image-server/v1/productTypes/175/views/1/appearances/2?width=42&amp;height=42" type="preview" mediaType="image/png"/>
        </resources>
        ...
    </productType>

    So, don’t hard code these URLs in your source code and use the provided data!

With that blog post, you learned how our product type model works and how you can retrieve the required XML descriptions and images for product types from our API. In the following blog posts, I will describe our product and design model in more detail.

Please also have a look at the other articles in the series “API Terminology Explained”:

—————————————
Martin Breest
Platform Evangelist