Pattern Design API Technical Documentation

Via the Pattern Design API you can interact with the Pattern Design Platform. There are three ways you can make use of our designs in your website/system.

embedding the API plugin in your website
using the API methods that provide live data (such as pattern/getCategories and pattern/search) and presenting the result on your website
- either on your server and embedding the results in your pages
- or from Javascript (for which we recommend the use of an access token)
downloading the data as a package, and importing them into your system (this works with the pattern/export method)

In all cases, you work with watermarked preview images until your customers actually order a pattern'ed product, and only then you retrieve the production-grade image from Pattern Design.

In the following diagram, you get an overview of what a typical API integration involves, embedded within an order workflow (relevant API calls are in monospace font)

General Information

The Pattern Design API is a REST API which can be accessed via HTTPS. In compliance with REST convention, querying calls use the HTTP GET method. Calls that create, modify or delete data use POST, PUT, PATCH or DELETE.

The API calls go to https://patterndesigns.com/api/rest/1.0/apiKey/group/action. The apiKey (or access token for access from Javscript) has to be provided with every call. The group is only used for structuring the api. The action is the actual name of the call that is performed.

The result depends the type of the call.

For normal operations (login, report a sale etc.) the success result is JSON

For operations that retrieve data (download a file), the success result is a stream of the requested data

If an operation is unsuccessful, there's always a JSON result

The JSON result consists of a result status and the actual returned values. If a call succeeds, the result status is "SUCCESS", in case of an error the result status is "ERROR". If a call is unsuccessful, also the HTTP response status is different from 200 (e.g. 401 when authentication fails).

All data are exchanged in UTF8 encoding. Monetary amount numbers are formatted in English locale, e.g. "8.99".

Authentication is performed via HMAC, see the HMAC authentication section. It is also possible to use whitelisted IPs that are allowed to make API calls. However, if possible, use HMAC because it is more flexible (i.e. works from several server, needs no reconfiguration if you move etc., cloud setting with no fixed IP addresses). In your API account's technical settings, you can manage the whitelisted IPs for your account.

Can I Integrate/Use the API from my Shop System?

Usually there's always a way, but as often, the answer is - it depends. For integrating the Pattern Design API you have two parts (as per the workflow outlined above).

The first one is displaying the designs, changing the colors (if that is used), and somehow storing that design choice (id, and maybe colors) with the selected product/cart item for later use. Most shop systems allow the use of custom HTML/CSS/Javascript, so the customization of the design selection/modification should be possible. Usually there is also a way to store product parameters with the cart item, so the chosen design (and maybe colors) can be stored in those.
The second one is getting the production-grade image (high-res JPG, PNG, etc.) from the API after the customer has completed the order (which contains the pattern id associated with the order item), and processing/forwarding it to your printing system or printshop. This is only directly possible if your shop system allows to execute server-side code. If this is not possible, a way to perform this is to have a batch job on another system that queries the completed orders (shop systems usually have an API for that) and performs the downloading and processing/forwarding step.

To wrap up, shop systems that let you write custom server-side code should allow for a straight-forward integration. Shop systems that allow no server-side code will require some additional mechanism for the production-grade images to be downloaded for production after the order has completed.

Sandbox - Test Environment

For testing purposes, please make use of apitest.patterndesigns.com (https://apitest.patterndesigns.com/api/rest/1.0/). This is a mirror of the production environment, which is updated each day on 01:00am CET. Thus user accounts from the live system appear on the sandbox the next day, and changes made to the test system will be reset each day. Pattern sales reported to the test environment will not be billed. You can use the sandbox for trying out the API before activating a subscription.

Thus you can either use your production account credentials on the test system, or create a new account (which will be purged when the system is updated. You will receive your API key for the test system immediately after registering at the test system.)

The only significant API difference to the production system is that the sale/download call will only return actual production images for a few designs, see the call's description.

Example

Request (try in your browser)

https://apitest.patterndesigns.com/api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/user/test?name=Tom

Response

{
  "result":"SUCCESS",
  "greeting":"Tom, have a nice day"
}

Error response

{
  "result":"ERROR",
  "errorCode":"3",
  "error":"The IP address of the server/client that issued the REST call is not on the whitelist",
  "details":"195.70.113.209"
}

Details

Required Authentication Information

In order to have access to the API, you need to have your API and HMAC key (and the API username and password for logging in to the account, where you can see your API and HMAC key).

For accessing the API from the browser (Javascript), please use an access token instead of the API key.

Languages

Several methods take a language parameter. Specify the language using the two-letter ISO 639 alpha-2 code (e.g. 'en' for Englisch). If the language is not specified or the specified language is not supported, the language defaults to English.

All major languages are supported (e.g. for getCountries), but the designs' texts (title etc.) are currently available only in English and German. Keywords are to a reduced extent also available in French, Spanish and Japanese

Currencies

Methods dealing with monetary amounts always include the currency of the amount as the ISO 4217 currency code

When returned as JSON, monetary values are in the following format:

{ "amount": 0.12,  "currency": "EUR", "symbol": "€" }

Image formats

Several methods will provide you with images, which have the following specifics:

repeat: small 150px image (repeatable)
gallery: small 150px x 150px image, square (not repeatable)
small: small 200px x 200px image, square (not repeatable)
medium: medium 400px image, with watermark (repeatable)
xlarge: xlarge 1000px image, with watermark (repeatable)
xlargeDiscreet: xlarge 1000px image with very lightweight watermark (repeatable)

For the repeat and medium images, the smaller dimension is the pixels specified above. E.g. for medium there are images that are 400x600 and 600x400.

For the xlarge and xlargeDiscreet images, the width is always 1000px. E.g. there are files with 1000x1500 and 1000x700.

Metadata

Some methods provide metadata about designs, which are described here in detail.

horizontalRapportsPostcard

The value horizontalRapportsPostcard (a floating point value between 1.5 and 5) describes how often design should be repeated to look good.

There's designs which look good in a single repeat, e.g. 1336, and ones that need to be repeated to look good, e.g. 557. With the horizontalRapportsPostcard you have a (initial) value how often the design should be repeated. The name of the parameter derives from how often a design needs to be repeated on a postcard to look good. For other products, you can use the horizontalRapportsPostcard as a basis and multiply this with a product-specific factor. E.g for wallpaper we have found that a repeat of horizontalRapportsPostcard * 3 is fine.

containsText

Whether a design contains text (not in the sense of embedded fonts, but that the image contains letters, symbols, numbers etc.), symbols or concrete objects . This is relevant for mirroring/flipping the design, which makes text illegible

HMAC authentication

A HMAC can be used to access the Pattern Design API without IP restriction. This works by signing additional request parameters with a secret key. You can get the secret key from the technical settings page in your account.

For using HMAC authentication, you need to include the following additional request parameters:

Parameter	Example	Description
timestamp	2014-04-10T05:31Z	ISO 8601 formatted UTC timestamp (with hours and minutes only) of the current moment with +/- 5 minutes tolerance for compensating for small differences in server times
nonce	lAJUCaY1G8	A random string as a salt for the hash, at least 10 characters
signature	49ac271988bdea9d19e833db3348d28b9a32f534e3b8fed75eefa79401f271f0	lowercase hex encoded HMAC hash signature

The signature is calculated as follows:

    HMAC-SHA256(secretKey, apiKey + timestamp + nonce)

The encoding used for the strings is UTF-8. For practical purposes at this point this is it the same as ASCII as there are only ASCII characters in the timestamp, nonce and signature parameters (unless you include non-ASCII characters in the nonce).

If the HMAC authentication is successful, the request will be processed normally. If HMAC authentication fails, an error is returned:

{
    "result": "ERROR",
    "errorCode": "21",
    "error": "The HMAC authentication failed"
}

Example request

https://apitest.patterndesigns.com/api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/user/test?name=Tom&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Hmac example

E.g. in PHP the signature calculation would look like this:

    $apiKey = 'h3vaT57GWThxW79HbLLosp6g';
    $timestamp = '2014-04-10T05:31Z';
    $nonce = 'lAJUCaY1G8';

    $stringToSign = $apiKey . $timestamp . $nonce;
    $key = '7803683af19135a91403a5d59b5d59613c63be448d4e7603924b7229f934e372';
    echo hash_hmac('sha256', $stringToSign, $key );
    // result: 49ac271988bdea9d19e833db3348d28b9a32f534e3b8fed75eefa79401f271f0

The following listing shows the complete code for making a test call with an API key and HMAC key

    $apiKey = '*your API key*';
    $key = '*your HMAC secret key from the technical settings page of your account*';

    $timestamp = gmdate("Y-m-d")."T".gmdate("H:i")."Z";
    $nonce = md5(time() + rand());

    $stringToSign = $apiKey . $timestamp . $nonce;
    $signature = hash_hmac('sha256', $stringToSign, $key );

    $curl = curl_init();
    $url = 'https://patterndesigns.com/api/rest/1.0/'.$apiKey.'/user/test?name=Tom&nonce='.$nonce.'&timestamp='.$timestamp.'&signature='.$signature;
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

    echo curl_exec($curl);

Below is a full example of a helper function for making API calls and an example for the most common backend calls:

//helper function for comfortably performing api calls
function patternDesignApiCall($method, $params = array(), $jsonResult = true, $post = false) {
    $apiKey = '*your api key*';
    $hmacKey = '*your HMAC secret key from the technical settings page of your account*';

    $timestamp = gmdate("Y-m-d")."T".gmdate("H:i")."Z";
    $nonce = md5(time() + rand());

    $stringToSign = $apiKey . $timestamp . $nonce;
    $signature = hash_hmac("sha256", $stringToSign, $hmacKey);

    $authenticationParams = array("nonce" => $nonce, "timestamp" => $timestamp, "signature" => $signature);

    $urlParams = http_build_query(array_merge($authenticationParams, $params));
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, "https://patterndesigns.com/api/rest/1.0/" . $apiKey . "/" . $method . "/?" . $urlParams);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);

    if ($post) {
        curl_setopt($curl, CURLOPT_POST, 1);
        curl_setopt($curl, CURLOPT_POSTFIELDS, '');
    }

    $result = curl_exec($curl);

    $httpCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);

    if(curl_errno($curl)) {
        error_log("Pattern Design API call $method (" . var_export($params, true) . ") returned curl error: " . curl_error($curl));
    } else if ($httpCode != 200) {
        error_log("Pattern Design API call $method (" . var_export($params, true) . ") resulted in http code $httpCode with response: $result");
    }

    curl_close($curl);

    if ($jsonResult) {
        return json_decode($result, true);
    } else {
        return $result;
    }
}


//designId and colors selected by the customer
$designId = 527;
$colors = "0000aa,bbbb00,ffaa00,caabff,aaaaff,ff0000";

//download preview image in user selected colors
file_put_contents("d:\\preview.png", patternDesignApiCall('pattern/recolor', array("id" => $designId, "colors" => $colors, "resolution" => "600"), false));

//report the sale
$orderReference="00023424";
$productPriceNet = "29,9";
$sale = patternDesignApiCall('sale/report', array("orderReference" => $orderReference, "designIds" => $designId, "productPriceNet" => $productPriceNet, "productName" => "Canvas"), true, true);


//download the production data
$downloadReference = $sale['downloadReferences'][0];
file_put_contents("d:\\production.png", patternDesignApiCall('sale/download', array("downloadReference" => $downloadReference, "fileType" => "png", "resolution" => "3000", "colors" => $colors), false));

Support for HTTPS/SSL image urls and CORS

All methods which return image urls have a useSecureUrls parameter which causes the returned image urls to use https. Please set this parameter to true (unless you have specific reasons for not requesting images over https).

Images have CORS support, i.e. can be requested from Javascript from any domain. Please note that in Chrome you need to work around image caching if you need CORS for the images (see this Stackoverflow post).

All API calls allow cross-origin requests and set the

Access-Control-Allow-Origin: *

header, but only when using an access token (don't use the API key for Javascript calls, please see getAccessToken).

Methods overview

API Methods

pattern/getCategories

Get the categories by which the patterns are organized

The designs are organized in categories, which themselves are organized in top-level categories:

Floral
    Leaves
    Mille Fleurs
    ...
Shapes
    Circles
    Stars
    ...
My Own Pattern Collection
...

Thus Floral and Shapes are top-level categories with the respective categories beneath them. There's two modes for using this method

retrieve the top-level categories first, and retrieve the categories beneath the top-level category afterwards (e.g. if you offer a user a drill-down selection)
retrieve the top-level categories and the categories all at once (e.g. for a menu where you present top-level categories and categories at once

Authentication

None

HTTP Method

GET

Parameters

Parameter	Type	Required	Details
topLevelCategoryId	string	no	if specified, the result is a list of the categories under the specified top-level category
includeSubcategories	boolean	no	determines whether the categories beneath the top-level categories are included in the result json. Applies only if no topLevelCategoryId is specified. Valid values are true and false
collectionsOnly	boolean	no	return only pattern collections, default false. This parameter doesn't apply if a topLevelCategoryId is specified. The result contains only active collections.
includeCollections	string	no	specify "true" to include your pattern collections in the result. Specify "belowCollectionsCategory" to put the collections into a dedicated top-level category. The collectionsOnly and includeCollections parameters, if set, override the collections setting from the collections administration UI. This parameter doesn't apply if a topLevelCategoryId is specified. The result contains only active collections.
language	string	no	see the languages section
useSecureUrls	boolean	no	if specified and set to true, the thumbnails urls are https urls
thumbnailType	string	no	small (150x150px, this is the default), medium (400x400px), repeat (same as the "repeat" image format)
customerKey	string	no	The customerKey for the customer for which you want to retrieve the collections (relevant if you use pattern collection customers).

Return values

Name	Type	Details
categories	json object	a list of categories with id, title and a thumbnail image url (thumbnails are 150x150 pixels)

Example

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/getCategories?includeSubcategories=true&useSecureUrls=true&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

{
  "result": "SUCCESS",
  "categories":
  [
    {
      "id": 2,
      "title": "Trends",
      "longTitle": "Trends",
      "thumbnail": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/categories/thumbnails/2.jpg",
      "isCollection": false,
      "containsPatterns": false,
      "categories":
      [
        {
          "id": 6,
          "title": "Miami Beach",
          "longTitle": "Miami Beach - trendy seamless pattern designs and vector ornaments",
          "thumbnail": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/categories/thumbnails/6.jpg",
          "isCollection": false,
          "containsPatterns": true
        },
        (...snip...)
      ]
    },
    {
      "id": 255,
      "title": "Timeless",
      "longTitle": "Timeless",
      "thumbnail": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/categories/thumbnails/255.jpg",
      "isCollection": false,
      "containsPatterns": false,
      "categories":
      [
        {
          "id": 4,
          "title": "Tasty",
          "longTitle": "Tasty - seamless pattern designs and ornaments in strong, lively colours",
          "thumbnail": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/categories/thumbnails/4.jpg",
          "isCollection": false,
          "containsPatterns": true
        },
       (...snip...)
      ]
    },
    {
      "id": 10001,
      "title": "My Own Pattern Collection",
      "longTitle": "My Own Pattern Collection",
      "thumbnail": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/gallery/2530.jpg",
      "isCollection": true,
      "containsPatterns": true
    }
  ]
}

pattern/getDesignerInfo

Get details about a designer

If you want to display more details about a designer (such as the profile image), this method if for you.

Authentication

None

HTTP Method

GET

Parameters

Parameter	Type	Required	Details
designerIds	integer	yes	Ids of the designers for which the details should be returned (you get the designer id via the designer.id result field from pattern/search)
language	string	no	see the languages section
useSecureUrls	boolean	no	if specified and set to true, the profile image is returned as a https url

Return values

Name	Type	Details
designer	json object	information about the designer, see the example for details. The profileImage image is 220px in width, the height is not fixed.

Example

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/getDesignerInfo?designerId=2&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

{
  "result": "SUCCESS",
  "designer": {
    "id": 2,
    "name": "Martina Stadler",
    "display": "Martina Stadler, patterndesigns.com",
    "profileUrl": "https://www.patterndesigns.com/en-designer-2/Martina-Stadler",
    "profileImage": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/designers/2-Martina-Stadler.jpg",
    "country": {
      "id": "AT",
      "name": "Austria"
    }
  }
}

pattern/search

Live search on all available patterns

Get a list patterns filtered by various criteria. None of the filter criteria is mandatory, and most can be combined. Use of multiple criteria will result in the set intersection of the results (e.g. if you specify a category and a color, you get the designs of that color in that category).

Only the ids parameter cannot be combined with other criteria as is explicitly fetches the designs with exactly the specified ids.

For the parameters that take ids, use the values you received from this or other methods - passing in other numbers will just yield no result

Authentication

None

HTTP Method

GET

Parameters

Parameter	Type	Required	Details
categoryIds	string	no	comma-separated list of numbers. Any top-level/non-top-level categories or collection from pattern/getCategories can be used. Specifying multiple categoryIds yields the union set of designs in these categories
designerIds	string	no	comma-separated list of numbers. Restricts the result to the specified designer's patterns. At the moment you can only get the designer ids from the result of this call (the designer.id resultField)
text	string	no	search the patterns for this text. The title, tags, description, and the categories a design appears in are used in the search. You'll want perform a text search when a user has entered a sufficient amount of text (e.g. 3 letters), as otherwise the results will be quite meaningless
colors	string	no	comma-separated list of colors in 6 digit hex notation (e.g. c0ffee). At the moment, only the first color from the list is used for search. This parameter isn't a filter but only sorts the search result by the similarity of a pattern's average color with the specified color.
aspectRatio	string	no	specify "square" to get only square patterns (1:1 in width-height)
recolorable	boolean	no	specify true to get only designs that are recolorable
ids	string	no	comma-separated list of numbers. This criterion overrules all other criteria, restricting the search result to the designs with exactly these ids
mergeIds	string	no	Allows to specify the ids parameter in addition to other filter criteria. Specify start or end to include the designs specified by the ids before or after the other result. Note that with this parameter, pagination is only applied to the non-ids search result, the designs specified by the ids are always added after pagination parameters are applied.
moreLikeThis	number	no	a design id for which similar designs should be returned. If you just want to get the most similar designs, add little other search restrictions, as the similarity will of course decline when restricting the search to a portion of designs (which will exclude designs with higher similarity from the excluded portion)
language	string	no	determines both the language in which the content is searched for the text search and the language that is used for the result (title etc.), see the languages section
limit	number	no	maximum number of returned designs, must be greater than zero. If you specify more than 100, at most 101 will be returned, defaults to 20
offset	number	no	offset into the search result, defaults to 0
useSecureUrls	boolean	no	if specified and set to true, the thumbnails urls are https urls
tags	text	no	show only patterns with the specified tags. Currently there is only the tag suited-for-wallpaper. Filtering by it retrieves only the patterns which we deem specifically suited for wallpaper. (the tags are not the same as the keywords)
maxFineElementsDisruptionResolution	number	no	see the corresponding resultField for a more detailed description. Valid values are between and including 25 and 2400
sort	string	no	Specify newestFirst to get the most recently published designs listed first. When not specifying newestFirst, the sorting behavior depends on the query. When the text or color parameters are specified, the order is determined by the degree of matching with the search criterion (i.e. better match with the specified text or closer to the specified color). Otherwise, the default sort is by popularity.
customerKey	string	no	The customerKey for the customer for which you want to retrieve the designs (relevant if you use pattern collection customers).
resultFields	string	no	comma-separated list of fields that are included in the result. Defaults to id,title,thumbnailGallery. For details about the images, see the section image formats. The available fields are listed below.

resultFields available fields

Name	Result data
id	id of the design
title	title of the design
description	prose description of the design
detailsUrl	a url pointing to the details page of the design on patterndesigns.com
keywords	keywords for the design
thumbnails.repeat	thumbnail, see image formats
thumbnails.gallery	thumbnail, see image formats
thumbnails.small	thumbnail, see image formats
thumbnails.medium	thumbnail, see image formats
thumbnails.xlarge	thumbnail, see image formats
thumbnails.xlargeDiscreet	thumbnail, see image formats
thumbnails.pdf	thumbnail, see image formats
thumbnailDimensions	include width and height for each thumbnail
metadata. horizontalRapportsPostcard	horizontalRapportsPostcard of design, a heuristic how often a design should be repeated to look good, see the respective metadata description
metadata.recolorable	whether the design can be recolored. Only designs that are recolorable can be used for the pattern/getColors and pattern/recolor methods
metadata.containsSvgGradient	whether the design (in the original SVG, and thus also in the derived formats like PDF) contains color gradients. This also means that a rastered image of the design will very likely contain more colors than the colors returned by pattern/getColors. Not all designs that look like they contain a gradient actually contains a gradient (i.e. have this flag set to true), some designs were created with lots of different colors (e.g. this one).
metadata.containsSvgTransparency	whether the design (in the original SVG, and thus also in the derived formats like PDF) contains transparency effects. This also means that a rastered image of the design will very likely contain more colors than the colors returned by pattern/getColors.
metadata.repeatType	the repeat type of the design - either full, horizontal, vertical. Design is intended to be repeated only in a single direction (i.e. it is a border/bordure). For custom designs, this is the value of the repeat type setting.
metadata. fineElementsDisruptionResolution	a heuristic at which downsampling resolution (without interpolation, i.e. nearest neighbour) the design starts to deteriorate (fine elements break up into single pixels, thus the name). It is an indicator for the robustness of the design when the size is reduced, an can be used for limiting the minimum tile size. This is a very specific value, which you likely don't need in normal use cases.
designer.id	designer's id
designer.name	designer's name
designer.display	correct display of designer as the creator of a design
designer.profileUrl	url of the designer's profile
priceOnlineShop	the Vector Unlimited license price in the patterndesigns.com online shop as the following property of the pattern result object: "priceOnlineShop": { "EUR": 40.0 }
customImageTypeId/paletteId	if you are an API user who has custom images types and palettes, you can specify the custom image types and palettes like this: resultFields=customImageTypeId.1,paletteId.1,paletteId.2,... The result is available as a field on the pattern result object: "customImages": [ { "customImageTypeId": 1, "paletteId": 1, "url": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/users/1/custom..." }, { "customImageTypeId": 1, "paletteId": 2, "url": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/users/1/custom..." } ]

Return values

Name	Type	Details
patterns	json object	a list of the designs matching the filter criteria containing the specified result fields, for details see the exhaustive example

Example

Request

GET api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/search?categoryIds=2&limit=1&offset=253&language=en&resultFields=id,title,description,keywords,metadata.horizontalRapportsPostcard, designer.id,designer.name,designer.profileUrl,designer.display, thumbnails.repeat,thumbnails.gallery,thumbnails.small, thumbnails.medium,thumbnails.xlarge,thumbnailDimensions&useSecureUrls=true&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

The totalHits value is the total number of results that was found for the search, independend of the offset/limit parameters, and can be used for determining the number of pages for pagination.

{
  "result": "SUCCESS",
  "totalHits": 312,
  "patterns":
  [
    {
      "id": 3136,
      "title": "Dekora Blue",
      "description": "Sweet design in classic blue and white colors.",
      "keywords": "Cottage, Fantasy, Floral, Flowers, Blue, White, Tile",
      "metadata": {
        "horizontalRapportsPostcard": 2.5
      },
      "designer": {
        "id": "162",
        "name": "Leska Hamaty",
        "profileUrl": "https://www.patterndesigns.com/en-designer-162/Leska-Hamaty",
        "display": "Leska Hamaty, patterndesigns.com"
      },
      "thumbnails": {
        "gallery": {
          "url": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/gallery/3136.jpg",
          "width": 150,
          "height": 150
        },
        "repeat": {
          "url": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/repeat/3136.jpg",
          "width": 150,
          "height": 150
        },
        "small": {
          "url": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/detail/small/3136.jpg",
          "width": 200,
          "height": 200
        },
        "medium": {
          "url": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/detail/medium/3136.jpg",
          "width": 400,
          "height": 400
        },
        "xlarge": {
          "url": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/detail/xlarge/3136.png",
          "width": 1000,
          "height": 1000
        }
      }
    }
  ]
}

pattern/getColors

Get the different colors in the vector image of the design

Returns colors in the vector image for use with the pattern/recolor method.

Please note that the colors do not always completely correspond to the colors in the final rendered image, as due to gradients or transparency in some patterns the colors can be mixed or overlaid (e.g. this pattern consists of overlaid transparent shapes that result in many more colors in the final rendered image compared to the colors you receive by this method)

Authentication

None

HTTP Method

GET

Parameters

Parameter	Type	Required	Details
id	integer	yes	id of a design

Return values

Name	Type	Details
colors	json object	a list of RGB-colors in six-digit hex notation (red = ff0000). Roughly 80% of the patterns have less than different 10 colors. The maximum number of colors returned is 200 (designs with more colors are not recolorable). For most of the patterns the first color is the background color, so even if a pattern has lots of colors, manual recoloring can make sense by changing the most significant ones

If the design is not recolorable, you'll receive a specific error code, see the example responses for details. You can find out upfront whether a design is recolorable via the corresponding result field in the pattern/search method.

Example

Request

GET api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/getColors?id=527&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

If the design is recolorable, a list of colors is returned:

{
  "result": "SUCCESS",
  "colors":
  [
    "504e2a",
    "b18048",
    "f19426",
    "ece24b",
    "7b753f",
    "e41270",
    "c10048",
    "5eb693"
  ]
}

If the design is not recolorable, an error is returned:

{ "result": "ERROR", "errorCode": "4000", "error": "The specified design is not recolorable", "details": "id:2987" }

pattern/getPalettes

Get the predefined palettes

Returns predefined palettes applicable for the pattern/recolor and sale/download methods.

Authentication

None

HTTP Method

GET

Parameters

This method currently has no parameters.

Return values

Name	Type	Details
color palettes	json object	A list of color palettes for use with the recolor method

Example

Request

GET api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/getPalettes?nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

If the design is recolorable, a list of colors is returned:

        {
        "result": "SUCCESS",
        "palettes":
        [
            { "id": : "hue_red", "previewColor": "ff0000" },
            { "id": : "hue_blue", "previewColor": "aaaaff" },
            (... snip ...)
        ]
        }

pattern/recolor

Get a recolored version of a design. The new colors can be created on the basis of the colors retrieved with pattern/getColors

This generic method lets you implement all thinkable color manipulation tools, e.g. single color picking, applying predefined palettes or color space operations such as changing saturation.

Authentication

None

HTTP Method

GET

Parameters

Parameter	Type	Required	Details
id	integer	yes	id of a design
colors	string	no	Comma-separated list of colors in six-digit hex format. The order corresponds to the colors as returned by pattern/getColors. If you specify more colors, the superfluous colors are ignored. If you specify less colors then the rest of the colors remains the same as in the original designs. Specifying no colors allows you to get an image even for non-recolorable designs. Only either the colors or the palette parameter can be for used in the same method call
palette	string	no	One of the palettes returned by the getPalettes method. Only either the colors or the palette parameter can be for used in the same method call
resolution	integer	no	the width of the returned image in pixels, defaults to 400
watermarkType	string	no	specify "discreet" to get a lightweight watermark corresponding to the xlargeDiscreet image format, otherwise the normal watermark is used
antialiasing	boolean	no	whether the downloaded image file has antialiasing applied. The default value is true. Useful if you do color reduced printing (where antialiasing produced unwanted additional colors). Don't use this parameter unless you know what you're doing, because turning off antialiasing will result in a lower perceived image quality
scale	floating point number	no	optionally indicates the scale of the image. The default value is 1.0. Valid values are between and including 0.05 (pattern is repeated 20 times) and 10.0 (only one tenth of the pattern will be visible). The aspect-ratio of the resulting image is the same as of the original pattern, i.e. it's repeated the same number of times in both dimensions

Return values

The recolor method will return a PNG image. If you specify the colors parameter, these colors will be used. Without specifying the colors parameter, for all designs (even non-recolorable ones) an image in the original colors is returned

If the design is not recolorable and you specify colors, you'll receive a specific error code, see the example responses for details. You can find out upfront whether a design is recolorable via the corresponding result field in the pattern/search method.

Example

Request

GET api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/recolor?id=527&colors=00aa00,00ff00&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

A PNG image if the design is recolorable.

If the design is not recolorable, an error is returned:

{ "result": "ERROR", "errorCode": "4000", "error": "The specified design is not recolorable", "details": "id:2987" }

pattern/renderAsProduct

Get a 3D rendered product preview with the specified design on it.

This method is only available if you have activated the respective subscription, but you can try it out with pattern ids up to id 540.

Regarding recoloring usage, please see the pattern/recolor method.

Authentication

None

HTTP Method

GET

Parameters

Parameter	Type	Required	Details
id	integer	yes	id of a design
colors	string	no	Comma-separated list of colors in six-digit hex format. The order corresponds to the colors as returned by pattern/getColors. If you specify more colors, the superfluous colors are ignored. If you specify less colors then the rest of the colors remains the same as in the original designs. Specifying no colors allows you to get an image even for non-recolorable designs. Only either the colors or the palette parameter can be for used in the same method call
palette	string	no	One of the palettes returned by the getPalettes method. Only either the colors or the palette parameter can be for used in the same method call
width	integer	no	the width of the returned image in pixels, defaults to 400, 1000 at most
height	integer	no	the height of the returned image in pixels, defaults to width * 0.5625 (16:9), 1000 at most
scale	floating-point	no	the scale at which the pattern is applied to the model. Defaults to 1. Values large than 1 lead to the pattern repeating more often on the model, values smaller than 1 repeat the pattern less often
model	string	yes	identifier of your model. If not specified, our default pillow model will be rendered
watermarkType	string	no	specify "discreet" to get a lightweight watermark corresponding to the xlargeDiscreet image format, otherwise the normal watermark is used

Return values

A PNG image with the specified model and design. If colors are specified, the same constraints apply as for the pattern/recolor method

Example

Request

GET api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/renderAsProduct?id=527&colors=00aa00,00ff00&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

A PNG image, or a JSON result with error details if there were problems.

pattern/export

Download an export of the pattern data

Use the aboveId and belowId parameters to paginate through the patterns via repeated calls. Use a page size of e.g. 10000 to iterate through all patterns (e.g. aboveId=0&belowId=10001, aboveId=10000&belowId=20001, ...). The stopping condition is when the result doesn't contain patterns anymore.

This call does not return instantly but take some time (potentially dozens of seconds) depending on the amount of requested patterns. The export call is not intended for use as a live source of all patterns (for this it also takes too long), but rather for getting the pattern data on a regular basis (e.g. once per day). For live data, see the pattern/getCategories and pattern/search methods.

If you use this method to import the patterns into your system, you will need to update the data at regular intervals in order to get new patterns and delete the ones we have taken offline at a designer's request

This call is allowed only once per minute per user, as it takes some time and resources to assemble the relevant data.

Authentication

None

HTTP Method

GET

Parameters

Parameter	Type	Required	Details
aboveId	integer	no	if specified, the export will only include patterns with an id higher than this value (useful for getting only newly added patterns instead of the full export). The disadvantage is that changes to existing patterns (e.g. use in new categories) will be missed if this option is used
belowId	integer	no	if specified, the export will only include patterns with an id lower than this value (can be used in conjunction with aboveId to get the export in several parts)
format	string	no	specify the value 'xml' if you prefer to directly get the xml file instead of a zip file with an xml file with it. Specify 'csv' to get a CSV file (in a zip file)
useSecureUrls	boolean	no	if specified and set to true, the thumbnails urls are https urls
columns	string	no	comma-separated list of the columns you want to appear in the csv file, only relevant for csv export, defaults to all available columns. For the column names, see the full csv file. An example is id,categories.nameEN,data.titleEN,data.descriptionEN,thumbnails.detail.medium.path

Return values

When the call succeeds, the result is, depending wether you specify the format parameter

a zipped file with a file named "patterns.xml" in it.
if format=xml is set, the requested data directly as xml

In case of an error, the result is (as with all other calls) a JSON string with error details. The xml file structure is as in the following example.

    <patternData>
    <generalData>
        <agency displayName='Pattern Design' name='Pattern Design GmbH' email='info@patterndesigns.com' cowner='Pattern Design GmbH' cbank='Raika Region Ried' cbic='RZOOAT2L450' ciban='AT82 3445 0000 0431 9638' street='Haidermuehle' city='Mondsee' zip='5310' country='Austria' streetNumber='52' ustid='ATU65824334' phone='+43 699 197 85 410' fax='+43 6232 90 30 310 30' />
        <designers>
            <designer id='2' firstname='Martina' name='Stadler' sex='female' display='Martina Stadler, patterndesigns.com' profilePageDE='www.patterndesigns.com/designer-2/MartinaStadler' profilePageEN='www.patterndesigns.com/en-designer-2/MartinaStadler' />
        </designers>
        <categories>
            <category id='2' nameDE='Trends' nameEN='Trends' shortNameDE='Trends' shortNameEN='Trends'>
                <category id='6' nameDE='Miami Beach - trendige Designmuster und Ornamente' nameEN='Miami Beach - trendy seamless pattern designs and vector ornaments' shortNameDE='Miami Beach' shortNameEN='Miami Beach'/>
            </category>
        </categories>
    </generalData>
    <patterns>
        <pattern id='527'>
            <data>
                <titleDE>Pfauenaugen</titleDE>
                <titleEN>Peacock</titleEN>
                <descriptionDE>Das moderne, orientalisch wirkende Muster bildet einen spannenden Kontrast zum dunklen Hintergrund.</descriptionDE>
                <descriptionEN>The modern and orientalistic appearing design builds an exciting contrast to the dark background.</descriptionEN>
                <keywordsDE>Ethno, Federn, Pfau, Orientalisch</keywordsDE>
                <keywordsEN>Ethno, Feathers, Peacock, Orientalistic</keywordsEN>
                <designer id='2' />
            </data>
            <metaData>
                <hasColorGradient>false</hasColorGradient>
                <containsText>false</containsText>
                <badSilhouetteAgainstBlack>false</badSilhouetteAgainstBlack>
                <badSilhouetteAgainstWhite>false</badSilhouetteAgainstWhite>
                <horizontalRapportsPostcard>2.0</horizontalRapportsPostcard>
                <numberOfPixelColors>8</numberOfPixelColors>
                <containsSvgGradient>false</containsSvgGradient>
                <containsSvgTransparency>true</containsSvgTransparency>
            </metaData>
            <thumbnails>
                <repeat width='150' height='177'>
                    <path>https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/repeat/527.jpg</path>
                </repeat>
                <gallery width='150' height='150'>
                    <path>https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/gallery/527.jpg</path>
                </gallery>
                <detail>
                    <small width='200' height='200'>
                        <path>https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/detail/small/527.jpg</path>
                    </small>
                    <medium width='400' height='472'>
                        <path>https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/detail/medium/527.jpg</path>
                    </medium>
                    <xlarge width='1000' height='1179'>
                        <path>https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/detail/xlarge/527.png</path>
                    </xlarge>
                </detail>
            </thumbnails>
            <patternToCategory>
                <category id='315' />
                <category id='263' />
                <category id='311' />
            </patternToCategory>
        </pattern>
    </patterns>
</patternData>

For details about the images, see the section image formats

Example

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/export?nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

(zip file as stream)

sale/report

Report the sale of one pattern'ed product in order to subsequently download it via the sale/download call.

If your order contains several products with patterns, you need to call sale/report for each product (order item). This also applies for several identical products (for each of which you need an individual call), as outlined in the licensing conditions.

Please note that the sale/report method only prepares the sale. Only when the actual download is performed the license fee is charged and the sale shows up in the list of purchases. The reason for this is that when the sale/report return value cannot be received or processed for whatever cause, no costs are incurred. This also matches the business definition - if you don't get anything, you don't pay.

Authentication

HMAC required

HTTP Method

POST

Parameters

Parameter	Type	Required	Details
orderReference	string	yes	reference to the order with which the product was purchased (i.e. the order id from your system), between 1 and 100 characters. Needed for associating the sale in your system with the sale of the patterns (e.g. if there's a problem with a pattern sale, we can tell you for which of your orders it was). You can have multipe calls with the same orderReference (just as you can have multiple product sales within one order)
designIds	string	yes	comma-separated list of design ids of the designs used on this product (e.g. for different front/back side of a pattern'ed pillow you specify both designs in designIds)
productPriceNet	monetary	yes	the product price net of the sold product without the license costs for the designs. All the prices in this method use the dot as the decimal separator, e.g. 3.14. For compatibility reasons we also still support the comma as the decimal separator (e.g. 3,14, as used in several European countries).
productName	string	no	a textual description of the sold product
currency	string	no	the currency of the productPriceNet parameter, i.e. the currency in which you billed this sale. For the format see the currencies section. This parameter is optional and defaults to the sales currency of your API account (which is shown in the technical settings of your API account). Please contact us if you're not sure if you should specify a currency here.
sessionToken	string	no (only required when not using HMAC authentication)	session token returned by login call - (obsolete - please use HMAC authentication instead)

Return values

Name	Type	Details
saleReference	integer	the reference of the reporting of this sale with the Pattern Design Platform. Allows to associate this call with a sale in your system
downloadReferences	list of integers	references to be used for downloading the patterns used for the sale

In case there's insufficient funds, the sale will not be performed and an error will be returned (errorCode 2006, message "Reporting the sale failed - there is insufficient credits for the user").

Example

Here's two examples for a better understanding of the submitted amount.

One product that costs 100 without the pattern, so the productPriceNet is 100. You will then charge the customer 100 plus the licenseFee (which is 12%) of this price.

If you charge a fixed amount, e.g. EUR 200, for your product, the price (net of the license fee) you report to us is 200 / 1.12, thus 178.57

Request

POST /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/sale/report?sessionToken=Rqk3Cfd2YSTvXkc8nmuzaZD9&orderReference=1234&designIds=593%2C593%2C594&productPriceNet=10.99& productName=Table&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

(url encoded %2C = comma)

Response

        {
        "result":"SUCCESS",
        "saleReference":37,
        "downloadReferences":[98,99,100]
        }

In case of insufficient funds

        {
        "result":"ERROR",
        "errorCode":"2006",
        "error":"Reporting the sale failed - there is insufficient credits for the user",
        "details":"credits 100.00 vs. license fee 360.00"
        }

sale/download

Download the production image file for a pattern that was part of a sale reported via sale/report.

Besides SVG (which is our base format) we also offer the image in the PDF and JPG formats. Please do not rasterize the SVGs with imagemagick or rsvg-convert, this results in white/transparent borders for a signification portion of SVG files. If you can work with the jpeg version, use it (for tiling the jpeg images imagemagick is fine, though). If you have special requirements, just contact us.

Please note that downloading a design from a sale reported with sale/report actually commits/finalizes the sale and thus deducts the license fee from the balance and adds the sale to the list of purchases.

This endpoint can be called multiple times for the same downloadReference without incurring multiple charges, so you retry e.g. in case of connection issues. The ability to retry the download is also the reason for having the dedicated report and download endpoints.

Authentication

HMAC required

HTTP Method

GET

Parameters

Parameter	Type	Required	Details
downloadReference	integer	yes	a download reference returned by the sale/report call
fileType	string	no	one of svgz, svg, pdf, jpg, png, (not specifying the fileType defaults to svgz). Click the link on the filetype to download a sample. Here is one for a repeat pdf with the pattern repeated twice (with 1000 PDF units size, i.e. 352.8mm).
resolution	number	no	JPG/PNG: the width of the jpg file that is being downloaded, a number between 1 and 10000. If not specified it defaults to 1000. This parameter applies only for raster (jpg or png) downloads. Please note that at high resolution the image processing and download may take a while (up to 2 minutes for complex designs at high resolutions) PDF: decimal (e.g. 103.52) - width of the PDF in PDF units (1/72 inch). If the resolution is specified, height and scale need to be specified, too.
antialiasing	boolean	no	whether the downloaded image file has antialiasing applied. The default value is true. This parameter applies only for png downloads. Turning off antialiasing (i.e. using false for this parameter) is useful if you do color reduced printing (where antialiasing produced unwanted additional colors). Don't use this parameter unless you know what you're doing, because turning off antialiasing will result in a lower perceived image quality
colors	string	no	comma-separated list of six-digit hex colors that will be applied to the design that is downloaded. See the pattern/getColors and pattern/recolor methods. Only either the colors or the palette parameter can be for used in the same method call
palette	string	no	One of the palettes returned by the getPalettes method. Only either the colors or the palette parameter can be for used in the same method call.
sessionToken	string	no (only required when not using HMAC authentication)	session token returned by login call - (obsolete - please use HMAC authentication instead)
height	number	no	JPG/PNG: the desired height of the result image in pixels, a number between 1 and 10000, can only be used in combination with resolution and scale. Auto-height feature: Omitting the height while specifying resolution and/or scale will produce an image that is exactly one pattern tile high (and thus being vertically repeatable), the exact height depending on the pattern's aspect ratio and the scale. Please note that for high values for resolution and scale (e.g. 10000 and 10), the height and thus the resulting image would become impracticably big. Such requests will return an error if the resulting image is roughly bigger than 300 megapixels (i.e. bigger than 10000 x 30000). PDF: height of the PDF in PDF units (1/72 inch) as a decimal number (e.g. 103.52). If the height is specified, scale and resolution need to be specified, too.
scale	number	no	The scale of the pattern. Not applicable for SVGZ. 1 = pattern tile fills the full width, 0.5 = tile width is half the width, i.e. the pattern is shown 2 times horizontally etc., 2 = pattern is zoomed in by factor 2 (only the left half of the pattern will be visible). JPG/PNG: When the scale is specified, resolution must also be specified. The scale can only be in the range of 0.0001 to 1000. PDF: When the height is specified, scale and resolution need to be specified, too.
offsetX	number	no	float - offset of the pattern from the left border. JPG/PNG: in pixels. Only applicable when resolution is also specified. PDF: in PDF units (1/72 inch). Only applicable for PDF with specified resolution, height and scale.
offsetY	number	no	float - offset of the pattern from the top border. JPG/PNG: in pixels. Only applicable when resolution is also specified. PDF: in PDF units (1/72 inch). Only applicable for PDF with specified resolution, height and scale.

Return values

When the call succeeds, the result is the requested file directly as a stream. In case of an error, the result is (as with all other calls) a JSON string with error details.

Depending on the fileType parameter, the following content is returned

svgz or no fileType: the design as a svgz file (a gzipped svg)
pdf: a vector pdf
jpg: the design in jpg format with the specified width, without watermark. The height will depend on the aspect-ratio of the design and might be smaller or larger than the width.

In case there's insufficient funds, the download will not be performed and an error will be returned (errorCode 2006, message "Reporting the sale failed - there is insufficient credits for the user"). Normally, if you sucessfully call sale/report, the sale will also be downloadable. But because only the download of a design of a sale actually finalizes/commits that sale, if the balance is low and concurrent purchases are made, report might succeed while download then fails because of another download call that was faster.

Note: Note that on the test (sandbox) system, only designs up to id 540 (i.e. 527, 529, 530, 531, ...) will download normally. For all others you will receive the files of the same design 527 for all calls. (we can't give away all designs on the test system)

If you specify colors for a design that is not recolorable, you will receive an error.

Example

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/sale/download?sessionToken=45vxypa1JD7WJofWbb7gM9u6&downloadReference=110&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

(requested file as stream)

See the note in the return values section for special handling on the test system.

In case of insufficient funds, an error is returned.

        {
        "result":"ERROR",
        "errorCode":"2006",
        "error":"Reporting the sale failed - there is insufficient credits for the user",
        "details":"credits 100.00 vs. license fee 360.00"
        }

sale/cancel

Cancel a sale previously reported via sale/report.

Can only be called by API users who have an arrangement with Pattern Design that allows them to cancel the sales up to a certain age.

Authentication

HMAC required

HTTP Method

POST

Parameters

Parameter	Type	Required	Details
saleReference	integer	yes	the sale reference returned by the sale/report call.

Return values

When the call succeeds, the result is a JSON object with result set to SUCCESS. In case of an error, the result is (as with all other calls) a JSON string with error details. Possible errors are an invalid saleReference and the attempt to cancel a sale which is already too old and thus can't be canceled anymore.

Example

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/sale/cancel?saleReference=123456&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

Success:

        {
        "result": "SUCCESS",
        }

In case of a sale whose age exceeds the timespan during which sales can be canceled an error is returned:

        {
        "result":"ERROR",
        "errorCode":"2022",
        "error":"Canceling the sale failed - the sale is older than the timespan during which sales can be canceled",
        "details":"Sale 123456 cannot be canceled because it is already older (103 days since 2018-11-23 23:35:15) than the cancelable timespan (42 days)"
        }

user/getAccessToken

Get the access token for the API plugin or access from Javascript. Please use an access token when accessing the API from Javascript.

This method provides you with the access token you need to pass to the API plugin. The token is valid for 1 month (which should be enough so that it lasts for the timespan a user uses a website).

You can also use a non-expiring access token instead of a generating one with this call - you can find it in your account's technical settings.

The access token is then used in the API calls in place of the API key. The access token (which works only for public methods) allows to keep your API key private to your server, so anyone inspecting your website will only see the limited token.

Calls (from Javascript) with the access token will have wildcard CORS header. You can also use JSONP which has no CORS restriction. For using JSONP specify a 'callback' parameter.

Authentication

None

HTTP Method

GET

Parameters

None

Return values

The access token.

Example

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/user/getAccessToken?nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

        {
        "result": "SUCCESS",
        "token": "152-1402985214238-0112652451-490289479d235363121825431dce1bb917f28047a9a9a317c2451a1e6806f937"
        }

user/login

Retrieves a session token for calls requiring authentication.

This method is obsolete - please use HMAC authentication, because it provides a stronger protection (and doesn't break at password change), and makes the session token (and thus the user/login call) obsolete for all methods that require authentication.

The login method can be used to retrieve the session token for subsequent calls that require authentication. The session token is valid for 30 minutes.

Authentication

None

HTTP Method

POST

Parameters

Parameter	Type	Required	Details
username	string	yes	your API username
password	string	yes	your API password

Return values

Name	Type	Details
sessionToken	string	the session token for subsequent authenticated calls
apiKey	string	the API key for the user that was logged in

For referral partners there are two specific error codes:

1003 ("The login failed - the API key of the user does not match the provided API key of the request"). In this case the API user was not associated with your referral partner account.
1004 ("The login failed - the user is a website user and does not have an API account"). In this case the user has only an account on the Pattern Design website, but not for the API

Example

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/user/login?username=test&password=test&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

        {
        "result":"SUCCESS",
        "sessionToken":"LVFXFueEDiI88AzKiFruJkTC",
        "apiKey":"h3vaT57GWThxW79HbLLosp6g"
        }

Signs up a new api user

This method is only available to referral partners.

Upon sign-up, the user will also receive a welcome mail confirming the registration.

Authentication

None

HTTP Method

POST

Parameters

Parameter	Type	Required	Details
username	string	yes	username (not yet in use) for login, 6 to 255 characters
password	string	yes	password for login, 8 to 50 characters, must contain at least one number, one uppercase letter and one lowercase letter
company	string	yes	name of the company, between 3 and 50 characters
vatNumber	string	no	between 8 and 25 characters, not required at all for users from non-EU countries. Users from EU countries should specify it (otherwise they will be charged VAT). The validity of the VAT ID for users from EU countries will be validated using the EU VAT ID validation service
street	string	yes	street of the user's address, 5 to 50 characters
zipCode	string	yes	zip code of the user's address, 3 to 11 characters
city	string	yes	city of the user's address, 3 to 40 characters
country	string	yes	user's country - two-letter country code according to ISO 3166-1 alpha-2, as also returned by pattern/getCountries
website	string	yes	user's website - a valid URL in https://test.com format (at least 12 characters, maximum 250 characters)
shopSystem	string	yes	user's shop system (between 3 and 50 characters)
salutation	string	yes	Mr. or Ms.
firstName	string	yes	user's first name, between 2 and 30 characters
lastName	string	yes	user's last name, between 2 and 30 characters
position	string	yes	user's position in the company, between 2 and 50 characters
email	string	yes	user's email address, a valid email address, maximum 255 characters
phone	string	yes	user's phone number, between 5 and 255 characters
mobile	string	no	user's mobile phone number, between 5 and 255 characters
newsletter	boolean	yes	whether the user wants to receive the Pattern Design newsletter - false for no, true for yes
billingEmail	string	no	separate address for receiving billing invoices. Must be a valid email address, maximum 255 characters. If not specified, the address from the email parameter is used
language	string	no	The language used for validation messages. see the languages section. Currently for this method only English is supported.
userId	string	no	The id in your system of the user that's being signed up

Validation details

The parameters are validated, and all validation failures are reported.

The validation information is contained in a JSON object named validationErrors, and contains objects composed of the field name and the error code plus a human-readable validation message. The language of the message is determined by the language parameters. See the example response for details. The HTTP status for validation errors is 200 (OK) because the request as such is valid, but the JSON response's result field is set to VALIDATION_ERROR and the errorCode field is set to 19

There can also be multiple validation errors per field (e.g. the password can be weak and too long at the same time). Advanced validations (such as the VAT number check) are only performed after basic validation (not blank) succeeded. Please note that invalid values for the salutation, country and newsletter fields don't result in a validation error but in a regular error, because the user can only choose from pre-supplied values.

The following error codes can occur, depending on the field.

tooShort - if the supplied value is shorter than the minimum allowed length
tooLong - if the supplied value is longer than the maximum allowed length
blank - if a required field is empty
weakPassword - if the password is too weak (see the field for details)
urlInvalid - if the url is not valid
emailInvalid - when an email is not valid
unique - when the username is already in use
invalidVatNumberFormat - when the vat number's format is invalid
invalidVatNumber - when the vat number is invalid

Return values

Name	Type	Details
apiKey	string	the api key for the user that was signed up if the signup was successful
validationErrors	object	a list of validation errors if the signup failed due to validation errors

Example

Request

POST /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/user/signUp?username=testuser&password=neverguess&company=PatternFun,Inc&vatNumber=DE999999MN&street=Strada%20del%20Sol&zipCode=1234& city=Springfield&country=AT&website=http%3A%2F%2Fwww.test.com&shopSystem=joomshopping&salutation=Mr.&firstName=Bart&lastName=Simpson& position=CFO&email=bart%40test.com&phone=555-234-444&mobile=00453345&newsletter=true&billingEmail=invoice%40test.com&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

Success:

    {
    "result": "SUCCESS",
    "apiKey": "0ncdiFRMbdbrFWWukHzN78yc"
    }

Validation failure:

    {
    "result": "VALIDATION_ERROR",
    "errorCode": "19",
    "error": "The specified input failed validation",
    "validationErrors":
    [
    {
    "password": "tooShort",
    "validationMessage": "The password is too short."
    },
    {
    "password": "weakPassword",
    "validationMessage": "The password must contain at least a number, an uppercase and a lowercase letter."
    },
    {
    "email": "blank",
    "validationMessage": "The email cannot be blank."
    },
    {
    "firstName": "blank",
    "validationMessage": "The first name cannot be blank."
    },
    {
    "lastName": "blank",
    "validationMessage": "The last name cannot be blank."
    }
    ]
    }

user/getUserData

Retrieves the data for the currently logged in user

Authentication

HMAC required

HTTP Method

GET

Parameters

This method takes no parameters.

Return values

Name	Type	Details
userData	json object	jon object which contains the same values as the parameters for user/signup, except for the password.

Example

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/user/getUserData?sessionToken=E6laAlYttSOINiezNjoc5QPo&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

        {
        "result": "SUCCESS",
        "userData": {
        "username": "testuser",
        "company": "PatternFun,Inc",
        "vatNumber": "DE999999MN",
        "street": "Strada del Sol",
        "zipCode": "1234",
        "city": "Springfield",
        "country": "AT",
        "website": "https://www.test.com",
        "shopSystem": "joomshopping",
        "salutation": "Mr.",
        "firstName": "Bart",
        "lastName": "Simpson",
        "position": "CFO",
        "email": "bart@test.com",
        "phone": "555-234-444",
        "mobile": 00453345,
        "newsletter": "true",
        "billingEmail": "invoice@test.com"
        "credits": { "amount": 0.0, "currency": "EUR", "symbol": "€" },
        "paysWithSubscription" : false
        }
        }

user/listPurchases

List the past purchases of the API user

Allows to retrieve a list of the purchases that the API user made, either all purchases or aggregated by month. The result list is sorted newest first.

Authentication

None

HTTP Method

GET

Parameters

Parameter	Type	Required	Details
groupBy	String	no	If "month" is specified, the results will be grouped by month
limit	integer	no	Limits the number of retrieved sales, the maximum value is 100, the default is 50
offset	integer	no	Offset into the list of sales, the default value is 0

Return values

Depending on the groupBy parameter, the result is in one of the two formats (see the examples for the exact json format).

a list of all individual purchases with order reference, license costs and date (the date is in ISO 8601 including seconds
a list of the purchases aggregated by month with the aggregate license costs

For the representation of monatary values see also the currencies section.

Example

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/user/listPurchases?nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

Individual sales

        {
        "result": "SUCCESS",
        "purchases":
        [
        {
        "date": "2014-04-25T03:58:50Z",
        "orderReference": "1235",
        "quantity": 42,
        "licenseCosts": { "amount": 0.12,  "currency": "EUR", "symbol": "€" },
        "productName": "Towel",
        "designs": [ { "id": 4212 } ]
        },
        {
        "date": "2014-04-25T03:43:50Z",
        "orderReference": "1234",
        "quantity": 1,
        "licenseCosts": { "amount": 0.12, "currency": "EUR", "symbol": "€" },
        "productName": "Towel",
        "designs": [ { "id": 4212 } ]
        }
        }

Grouped sales

        {
        "result": "SUCCESS",
        "purchases":
        [
        {
        "year": 2014,
        "month": 4,
        "totalLicenseCosts": { "amount": 273.24, "currency": "EUR", "symbol": "€" }
        },
        {
        "year": 2014,
        "month": 3,
        "totalLicenseCosts": { "amount": 123.73, "currency": "EUR", "symbol": "€" }
        }
        ]
        }

general/getCountries

Get a list of available countries

Lists the countries that can be used for methods that take a country as a parameter

Authentication

None

HTTP Method

GET

Parameters

Parameter	Type	Required	Details
language	string	no	see the languages section

Return values

Name	Type	Details
countries	json object	the list of countries with the two-letter country code according to ISO 3166-1 alpha-2 as id and the name in the specified language

Example

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/general/getCountries?language=es&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

{
  "result": "SUCCESS",
  "countries":
  [
    {
      "id": "AF",
      "name": "Afganistán",
      "isEuCountry": false
    },
    (... snip ...)
    {
      "id": "ZW",
      "name": "Zimbabue"
      "isEuCountry": false
    }
  ]
}

pattern/collections

Gets a list of available collections of the authenticated user.

Lists metadata about all collections of this user. The metadata includes the ID property of a collection that defines the URL to obtain the patterns contained in a collection. Also, a display design is provided, which can be used as a preview image.

The contents of a collection can be either maintained in the settings section of the API page or through custom functionality in the client application by using API calls.

Authentication

HMAC required

HTTP Method

GET

Return values

Name	Type	Details
collections	json object	array of collection metadata objects

Example

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

{
  "result": "SUCCESS",
  "collections":
  [
    {
      "id": 4242,
      "title": "1920s",
      "displayDesign": 3761,
      "displayDesignUrl": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/gallery/3761.jpg",
      "categoryId": 1000004242,
      "isActive": true
    },
    (... snip ...)
    {
      "id": 4243,
      "title": "Miami Beach Party",
      "displayDesign": 3763,
      "displayDesignUrl": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/gallery/3763.jpg",
      "categoryId": 1000004243,
      "isActive": false
    }
  ]
}

pattern/collections/:collectionID

Gets an existing collection by ID.

The contents of a collection can be either maintained in the settings section of the API page or through custom functionality in the client application by using API calls.

Authentication

HMAC required

HTTP Method

GET

Return values

Name	Type	Details
id	integer	ID of the retrieved collection
title	string	Collection title
displayDesign	integer or null	Either the ID of a design to serve as the preview image of the collection or `null` if no displayDesign has been set
displayDesignUrl	string or null	Either an absolute URL to a non-tilable, square preview image for the collection or `null` if no displayDesign has been set
categoryId	integer	The categoryId for use in the pattern/search endpoint categoryIds parameter
isActive	boolean	true or false depending on the collection's active state
patterns	array	Array of unique integers each being the ID of one contained pattern

Example

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/4242&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

{
  "result": "SUCCESS",
  "collection": {
    "id": 4242,
    "title": "1920s",
    "displayDesign": 1024,
    "displayDesignUrl": "https://d1biw2rz2h5h5w.cloudfront.net/images/patterns/api/gallery/3761.jpg",
    "categoryId": 1000004242,
    "isActive": true
    "patterns": [ 1024, 311, 314 ]
  }
}

With malformed ID

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/elvis42&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

{
  "result": "ERROR",
  "errorCode": "12",
  "error": "The value of the given parameter cannot be interpreted as an integer",
  "details": "Resource ID could not be parsed to an integer: elvis42"
 }

With non-existent ID

Request

GET /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/999999&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

{
  "result": "ERROR",
  "errorCode": "107",
  "error": "The specified collection does not exist"
}

pattern/collections

Creates a new collection using the data sent in the request body.

The data must be a JSON object defining the properties "title" (must be non-empty), "displayDesign" (nullable) and "patterns". Failing to provide all properties makes the API call yield an error and not create a new collection.

Responds with a JSON object containing "id" and "location" of the newly created collection. "location" contains an absolute URL addressing the newly created resource. This location is also sent with the HTTP header Location.

Authentication

HMAC required

HTTP Method

POST

Return values

Name	Type	Details
id	integer	ID of the newly created collection
location	string	Relative URL to the newly created collection

Example

Request

POST /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

{
  "title": "Retro Pixelart",
  "displayDesign": null,
  "patterns": [
    1414,
    353252,
    7,
    42
  ]
}

Response

HTTP/1.1 200 OK
[...]
Location: https://patterndesigns.com/api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/42

{
  "result": "SUCCESS",
  "id": 42,
  "location": "https://patterndesigns.com/api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/42"
}

with missing properties

Request

{
  "title": "Futristic LED art",
  "patterns": [
    1414,
    353252,
    7,
    42
  ]
}

Response

{
  "result": "ERROR",
  "errorCode": "106",
  "error": "The sent resource does not contain all required properties",
  "details": "Missing properties: [displayDesign]"
}

with non-existing pattern ID in displayDesign or patterns

Request

{
  "title": "Han Dynasty Vases",
  "displayDesign": 9898989,
  "patterns": [
    807,
    9898989
  ]
}

Response

{
  "result": "ERROR",
  "errorCode": "100",
  "error": "The specified design does not exist"
}

with wrong type of title property

Request

{
  "title": true,
  "displayDesign": 1414,
  "patterns": [
    1414,
    353252,
    7,
    42
  ]
}

Response

{
  "result": "ERROR",
  "errorCode": "25",
  "error": "The given parameter is not a string",
  "details": "title must be a string"
}

with empty title property

Request

{
  "title": "",
  "displayDesign": 1414,
  "patterns": [
    1414,
    353252,
    7,
    42
  ]
}

Response

{
  "result": "ERROR",
  "errorCode": "109",
  "error": "The specified string is empty",
  "details": "title may not be empty"
}

with wrong type of displayDesign

Request

{
  "title": "Yodeling",
  "displayDesign": "1414",
  "patterns": [
    1414,
    353252,
    7,
    42
  ]
}

Response

{
  "result": "ERROR",
  "errorCode": "12",
  "error": "The value of the given parameter cannot be interpreted as an integer",
  "details": "displayDesign is required and needs to be either null or a valid integer, instead got: \"1414\""
}

with wrong type of patterns or design IDs contained in patterns

Request

{
  "title": "Victorian",
  "displayDesign": 1414,
  "patterns": [
    807,
    "x"
  ]
}

Response

{
  "result":"ERROR",
  "errorCode": "26",
  "error": "The given parameter is not a list of pattern IDs",
  "details": "list:[807, x]"
}

pattern/collections/:collectionID

Performs a full update of an existing collection using the data sent in the request body.

The data must be a JSON object defining the properties "title" (non-empty), "displayDesign" (nullable) and "pattterns".

If the given data does not define all collection properties, the API call yields an error and the collection is left in its previous state.

Authentication

HMAC required

HTTP Method

PUT

Example

Request

PUT /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/424242&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

{
  "title": "Retro Pixelart",
  "displayDesign": null,
  "patterns": [
    1414,
    353252,
    7,
    42
  ]
}

Response

HTTP/1.1 200 OK
[...]

{
  "result": "SUCCESS"
}

with missing properties

Request

PUT /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/123&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

{
  "title": "Futristic LED art",
  "patterns": [
    1414,
    353252,
    7,
    42
  ]
}

Response

{
  "result": "ERROR",
  "errorCode": "106",
  "error": "The sent resource does not contain all required properties",
  "details": "Missing properties: [displayDesign]"
}

with non-existing pattern ID in displayDesign or patterns

Request

{
  "title": "Han Dynasty Vases",
  "displayDesign": 9898989,
  "patterns": [
    807,
    9898989
  ]
}

Response

{
  "result": "ERROR",
  "errorCode": "100",
  "error": "The specified design does not exist"
}

with wrong type of title property

Request

{
  "title": true,
  "displayDesign": 1414,
  "patterns": [
    1414,
    353252,
    7,
    42
  ]
}

Response

{
  "result": "ERROR",
  "errorCode": "25",
  "error": "The given parameter is not a string",
  "details": "title must be a string"
}

with empty title property

Request

{
  "title": "",
  "displayDesign": 1414,
  "patterns": [
    1414,
    353252,
    7,
    42
  ]
}

Response

{
  "result": "ERROR",
  "errorCode": "109",
  "error": "The specified string is empty",
  "details": "title may not be empty"
}

with wrong type of displayDesign

Request

{
  "title": "Yodeling",
  "displayDesign": "1414",
  "patterns": [
    1414,
    353252,
    7,
    42
  ]
}

Response

{
  "result": "ERROR",
  "errorCode": "12",
  "error": "The value of the given parameter cannot be interpreted as an integer",
  "details": "displayDesign is required and needs to be either null or a valid integer, instead got: \"1414\""
}

with wrong type of patterns or design IDs contained in patterns

Request

{
  "title": "Victorian",
  "displayDesign": 1414,
  "patterns": [
    807,
    "x"
  ]
}

Response

{
  "result":"ERROR",
  "errorCode": "26",
  "error": "The given parameter is not a list of pattern IDs",
  "details": "list:[123, asdf]"
}

With malformed ID

Request

PUT /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/elvis42&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

{
  "result": "ERROR",
  "errorCode": "12",
  "error": "The value of the given parameter cannot be interpreted as an integer",
  "details": "Resource ID could not be parsed to an integer: elvis42"
}

With non-existent ID

Request

PUT /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/999999&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

{
  "result": "ERROR",
  "errorCode": "107",
  "error": "The specified collection does not exist"
}

pattern/collections/:collectionID

Performs a partial update of a collection by sending an update object in the request body.

An update object contains a "method" and a "data"-property, depending on the operation to perform.

method	usage	data
add	Appends patterns to the end of the collection. If a pattern is already present in the collection, it is silently ignored.	An array of pattern IDs.
remove	Removes patterns from the collection. If attempting to remove an ID that is not present in the collection, or when the list to remove contains duplicate IDs, the API yields an error and the collection is left in its previous state.	An array of pattern IDs.
set	Replaces any or all of `"title"`, `"displayDesign"` or `"patterns"` with a new value.	An object with any, some or all of the properties `"title"`, `"displayDesign"` or `"patterns"` defined. The value of `"title"` is expected to be a string, `"displayDesign"` is an integer and `"patterns"` is expected to be an array of pattern IDs.

Authentication

HMAC required

HTTP Method

PATCH

Example

Request

PATCH /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/424242&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

{
  "method": "add",
  "data": [ 420, 512, 1024 ]
}

Response

HTTP/1.1 200 OK
[...]

{
  "result": "SUCCESS"
}

with invalid method

Request

{
  "method": "eat",
  "data": "paprika"
}

Response

{
  "result": "ERROR",
  "errorCode": "11",
  "error": "The value of the given parameter is invalid",
  "details": "method:eat"
}

with invalid pattern list in add or remove

Request

{
    "method": "add",
    "data": [123, "asdf"]
}

Response

{
  "result": "ERROR",
  "errorCode": "26",
  "error": "The given parameter is not a list of pattern IDs",
  "details": "list:[123, asdf]"
}

With malformed ID

Request

PATCH /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/elvis42&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

{
  "result": "ERROR",
  "errorCode": "12",
  "error": "The value of the given parameter cannot be interpreted as an integer",
  "details": "Resource ID could not be parsed to an integer: elvis42"
}

With non-existent ID

Request

PATCH /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/999999&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

{
  "result": "ERROR",
  "errorCode": "107",
  "error": "The specified collection does not exist"
}

pattern/collections/:collectionID

Deletes the collection located at the URL.

Authentication

HMAC required

HTTP Method

DELETE

Example

Request

DELETE /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/424242&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

HTTP/1.1 200 OK
[...]

{
  "result": "SUCCESS"
}

With malformed ID

Request

DELETE /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/elvis42&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

{
  "result": "ERROR",
  "errorCode": "12",
  "error": "The value of the given parameter cannot be interpreted as an integer",
  "details": "Resource ID could not be parsed to an integer: elvis42"
}

With non-existent ID

Request

DELETE /api/rest/1.0/h3vaT57GWThxW79HbLLosp6g/pattern/collections/999999&nonce=83fad183e7740e820df9c3f1853f4480&timestamp=2014-04-10T06:22Z&signature=747e4c9ead23313011aed5902bbd6b100a419cbdb196d0e8e1ca9c611b4c1688

Response

{
  "result": "ERROR",
  "errorCode": "107",
  "error": "The specified collection does not exist"
}