Specifications API v2

Specification headings (e.g. Colour) are used by Products and product filtering in categories.

The Specifications admin API allows you to manage specification headings. You should be aware that altering or deleting existing specifications will affect all live products utilising the specification.

Scopes

Access to the Specification Values API requires that the client have the following scopes granted:

  • products - Permits write access to add, update or remove specifications.
  • products.readonly - Read only access to search or get specification data.

The Specification Object

A Specification represents a global heading used by Products and filtering.

description
Optional description for the specification up to 255 characters in length.
Defaults to null.
id read-only
An unsigned 64-bit integer, which is unique across all Specifications and all Evance Accounts.
reference
A unique string identifier for the specification e.g. color.
If omitted when adding a new Specification a new reference may be generated from the specification’s title.
May contain lower case characters: a-z 0-9 _ - up to 50 characters.
sequence
Indicates the display position of the specification on product profiles.
The sequence of specification items starts from 1 (the first item). You may supply the sequence when adding or updating specifications as an integer or as an object containing placement and id properties (see Sequencing Specifications below). If omitted when inserting a specification, the new item will be positioned last in the sequence.
title
The specification title up to 50 characters in length.
type
The type indicates how the Specification’s Values are used, displayed or validated.
May be one of the following:
  • string (default)
  • numeric requires that the specification’s values be an integer or decimal.
  • swatch allows values to include a color or image.
  • range allows values to have a minimum and maximum value.
uri
An internal help URI up to 255 characters may be associated with the specification offering helpful information regarding the specification. Must be an internal URI relative to root (e.g. /help/my-topic).

Example object

{
    "data": {
        "id": 53245,
        "reference": "color",
        "title": "Colour",
        "description": null,
        "uri": null,
        "type": "swatch",
        "sequence": 1
    }
}

Sequencing Specifications

The position of specifications is represented by the sequence property. When adding/modifying data you may stipulate the sequence by supplying either an integer (starting from 1) or a position object containing placementand id properties.

When supplying an integer, existing items with a sequence greater than or equal to the sequence supplied will increment by one. If you supply a sequence number greater than the current number of items, your specification will be positioned last and the appropriate sequence number will be recalculated and returned as part of the response.

Alternatively, you may supply a position object consisting of the following properties:

placement
May be one of the following:
  • first - insert or move the item to the first position.
  • last - insert or move the item to the last position.
  • before - insert or move the item in front of another item referenced by id (see below).
  • after - insert of move the item after another item referenced by id(see below).
id
Required when placement is either before or after. Represents the ID of another Specification.


Example

The example below shows a request to position the Specification before another with ID 1234.

{
    "data": {
        "sequence": {
            "placement": "before",
            "id": 1234
        }
    }
}

List/search Specifications

GET /api/v2/specifications.json

Get or search for one or more specification headings using a range of accepted query parameters.

Query Parameters

Accepts the following query parameters:

id:in
Return specifications by a comma-separated list of IDs.
id:min
Return specifications with an ID greater than or equal to that specified.
id:max
Return specifications with an ID less than or equal to that specified.
id:after
Return specifications with an ID greater than that specified.
id:before
Return specifications with an ID less than that specified.
reference:in

Return specifications matching references in a comma separated list (case-insensitive).

title:in

Return specifications matching titles in a comma separated list (case-insensitive).

type

Return specifications by type:

  • string
  • numeric
  • swatch
  • range


JSON response

Evance will return a JSON object containing the following properties:

success
A successful search request containing zero or more results will always return a true value.
status
An integer matching the HTTP response code. A successful request will have a status of 200.
data
An array containing zero or more Specification objects.
pagination
Search results include a pagination object contain information about the current page, total pages, the limit per page and the total number of results available.
  • limit - the number of results to return per page
  • page - the current page number
  • total - the total number of available results
  • totalPages - the total number of available pages of results
links
An object containing links to traverse available search results.
  • self - the URL for the current search.
  • previous - a URL for the previous results page, or null if there isn't one.
  • next - a URL for the next results page, or null if there isn't one


Example JSON response

In the example below you're able to see examples of different media types.

{
    "success": true,
    "status": 200,
    "data": [
        {
            "id": 53245,
            "reference": "color",
            "title": "Colour",
            "description": null,
            "uri": null,
            "type": "swatch",
            "sequence": 1
        },
        {
            "id": 75648,
            "reference": "size",
            "title": "Size",
            "description": null,
            "uri": null,
            "type": "string",
            "sequence": 2
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 100,
        "total": 2,
        "totalPages": 1
    },
    "links": {
        "self": "https://examples.evance.me/api/v2/specifications.json",
        "previous": null,
        "next": null
    }
}

Get a Specification

GET /api/v2/specifications/{id}.json

Retrieve a single Specification object using its ID.

URL parameters

id required
The ID of the Specification item is supplied as a path parameter.


Response

Returns an object with the following properties:

success
A boolean where a value of true represents a successful request.
status
The HTTP status code e.g. 200 for a successful request.
data
Contains the Specification object.


Example JSON response

{
    "success": true,
    "status": 200,
    "data": {
        "id": 53245,
        "reference": "color",
        "title": "Colour",
        "description": null,
        "uri": null,
        "type": "swatch",
        "sequence": 1
    }
}


Add a Specification

POST /api/v2/specifications.json

Add a Specification object.

Request body

Your request body must contain an object including:

data required
Containing a Specification object.

Example: minimum requirements

To add a Specification you must POST JSON to this resource within a data object. The minimum requirement for a specification is a title. All other properties (such as type and reference) will have defaults based upon the Specification settings.

{
    "data": {
        "title": "Size"
    }
}


Success response

Returns an object with the following properties:

success
A boolean where a value of true represents a successful request.
status
The HTTP status code e.g. 200 for a successful request.
data
Contains the Specification object.


Example JSON response

{
    "success": true,
    "status": 200,
    "data": {
        "id": 53245,
        "reference": "color",
        "title": "Colour",
        "description": null,
        "uri": null,
        "type": "swatch",
        "sequence": 1
    }
}


Error responses

If the Specification could not be created you will encounter a response with a 422 status code:

success
A boolean where a value of false means the object could not be created.
status
A response code of 422 means the object could not be created and you should check the errors property for further information.
context
The context property indicates where the error occurred. For a 422 error this will typically contain a value of data, indicating that there was an error with the data object supplied.
errors

Contains an array of error objects, each will have the following properties:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string (e.g. error.not-unique if the reference supplied is already in use).

Update a Specification

PUT /api/v2/specifications/{id}.json

Update an existing Specification by its ID.

URL parameters

id required
The ID of your Specification object


Request body

Your request body must contain an object including:

data required
Containing updates to your Specification object.


Example JSON request

To update a Specification you must PUT JSON to this resource within a data object. You do not need to supply all properties and may choose to only supply properties that require modifying.

{
    "data": {
        "title": "Shoe Size"
    }
}


Success response

If the Specification was updated successfully you should receive a response with a 200 status code:

success
A boolean where a value of true means the object was created successfully.
status
The HTTP status code e.g. 200 means the object was updated successfully.
data
Contains the Specification object you updated.


Error responses

If the Specification could not be updated you will encounter a response with either a 400, 404or 422status code:

success
A boolean where a value of false means the object could not be updated.
status
  • 400 may indicate that the ID was not provided.
  • 404 means object could not be found by the IDs provided.
  • 422 means the object could not be updated due to errors in the data.
context
  • parameters means the error is with the required id URL parameter.
  • data indicates an error within the object data.
errors

Contains an array of error objects, each will have the following properties:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string.

Delete a Specification

DELETE /api/v2/specifications/{id}.json

Delete a Specification by its ID.

URL parameters

id required
The ID of your Specification object


Request body

Does not require a payload

Success response

If the object was deleted successfully you should receive a response with a 204 status code and no body.

Error responses

If the object could not be deleted you may encounter a response with a 400, or 404 status code:

success
A boolean where a value of false means the object could not be deleted.
status
  • 400 may indicate that the ID was not provided, or the object could not be deleted for an unknown reason.
  • 404 indicates that the ID was provided, but the object could not be found.