Specification Values API v2

Specification Values are sub-objects of Specifications, which are assigned to Products as Product Specifications to be displayed on product profiles and for use in category filtering.

The Specification Values admin API allows you to manage the global values assigned to products. Altering or deleting existing values will affect live products utilising the value.

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 specification values.
  • products.readonly - Read only access to search or get specification value data.

Object structure

A Specification Value represents a global value used by Products and filtering.

color
When the specId relates to a Specification with a type of swatch, you may supply a hexadecimal colour reference (e.g. #ff0000). Defaults to null.
id read-only
An unsigned 64-bit integer, which is unique across all Specification Values and all Evance Accounts.
image
When the specId relates to a Specification with a type of swatch, you may supply an image. The URL to an image in the Media Library may be a JPEG, GIF, PNG, or SVG file up to 20MB in size.
Evance requires images for specification values to be imported into the Media Library. If you supply the image as a Data URI, or an external URL, Evance will import the image into the Media Library and an Evance CDN URL will be returned.
Defaults to null.
See Importing Images below.
maxValue
When the specId relates to a Specification with a type of range the maxValue supplied must contain a numeric value (signed or unsigned) greater than the value property.
Defaults to null.
sequence
Indicates the display position of the specification value on product profiles.
The sequence of items starts from 1 (the first item). You may supply the sequence when adding or updating specification values as an integer or as an object containing placement and id properties (see Sequencing Specification Values below). If omitted when inserting a specification value, the new item will be positioned last in the sequence.
specId
An unsigned 64-bit integer representing the Specification.
value
Required. The specification value may be a string up to 150 characters in length.
When the specId relates to a Specification with a type of numeric or range the value must contain a numeric value (signed or unsigned).

Importing Images

Importing new files for image properties may be done using one of the following methods:

  • Content URI
    Upload files to the Media Library manually through the Evance admin panel, then reference their location using a Content URI. For example, uploading a file named my-image-name.jpg to the images/products subfolder in the Media Library is referenced as ~/content/images/products/my-image-name.jpg. 

  • External URLs
    Evance will import file data from external URLs (http or https) into the Media Library. The file will be placed in a directory in the Media Library, which is calculated based on the URL and the mime type of the file.

  • Data URIs
    You can provide base64 encoded binary file data as a Data URI. Evance will calculate the directory within the Media Library based on the mime type of the file and the filename will be based on an md5 of the file contents.

When importing External URLs or Data URIs, you may want greater control over the resulting filename and location within the Media Library. Supply your data within an object consisting of src, filename and directory properties:

src
Required. May be either an absolute External URL, or a Data URI.
filename
Optional, allows you to set a preferred filename and extension for the image. For example my-file-name.png.
The file name should not include spaces or special characters.
The extension must be appropriate to the mime type.
directory
Optional, allows you to set a preferred directory within the Media Library and must be a valid Content URI starting with ~/content.

Example

The example below highlights how to specify both a filename and directory for an image imported using a Data URI.

{
    "data": {
        "image": {
            "src": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
            "filename": "my-image-name.png",
            "directory": "˜/content/images/products"
        }
    }
}

If the filename already exists within the directory supplied, the import may be ignored as Evance may assume the file already exists.

Sequencing specification values

The position of specification values is represented by the sequence property. When importing data you may adjust the sequence of your specification value by supplying either an integer (starting from 1) or a position object containing placement and id properties.

When supplying an integer, existing specification values 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 values, your object 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 object to the first position.
  • last - insert or move the object to the last position.
  • before - insert or move the object in front of another referenced by id (see below).
  • after - insert of move the object after another referenced by id(see below).
id
Required when placement is either before or after. Represents the ID of another Specification Value for the same Specification.

Example

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

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

List/search Values for a Specification

GET /api/v2/specifications/{specId}/values.json

Get or search for one or more values associated with a Specification using a range of accepted query parameters.

URL parameters

specId required
The specification ID is required.


Query Parameters

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


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 Value data 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 values for a Specification object type of swatch.

{
    "success": true,
    "status": 200,
    "data": [
        {
          "id": 1,
          "specId": 1,
          "value": "Red",
          "color": "#ff0000",
          "image": null,
          "maxValue": null,
          "sequence": 1
        },
        {
          "id": 2,
          "specId": 1,
          "value": "Green",
          "color": "#00ff00",
          "image": null,
          "maxValue": null,
          "sequence": 2
        },
        {
          "id": 3,
          "specId": 1,
          "value": "Blue",
          "color": "#0000ff",
          "image": null,
          "maxValue": null,
          "sequence": 3
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 100,
        "total": 3,
        "totalPages": 1
    },
    "links": {
        "self": "https://examples.evance.me/api/v2/specifications/1/values.json",
        "previous": null,
        "next": null
    }
}

Get a Specification Value

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

Retrieve a single Specification Value object for a Specification using its ID.

URL Parameters

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


Example JSON response

{
    "success": true,
    "status": 200,
    "data": {
        "id": 1,
        "specId": 1,
        "value": "Red",
        "color": "#ff0000",
        "image": null,
        "maxValue": null,
        "sequence": 1
    }
}


Add a Specification Value

POST /api/v2/specifications/{specId}/values.json

Add a Specification Value to a Specification heading.

URL parameters

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


Request body

Your request body must contain an object including:

data required
Containing a Specification Value object.


Example JSON response

To add a Specification Value you must POST JSON to this resource within a data object. The minimum requirements for a specification value depends on the type of specification the value is being added to. The default specification type is string requiring just a value.

{
    "data": {
        "value": "Red"
    }
}

For full details on the value object requirements see the Specification Value object.

Success responses

If the Specification Value object was created successfully you should receive a response with a 201 status code:

success
A boolean where a value of true means the object was created successfully.
status
The HTTP status code e.g. 201 means the object was created successfully.
data
Contains the Specification Value object you created including its new id and the URL imported for the image property (if applicable).


Error responses

If the Specification Value object 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, which may be used for translations.


Update a Specification Value

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

Update an existing Specification Value object by its ID.

URL parameters

id required
The ID of your Specification Value object.
specId required
The ID of your Specification heading object.


Request body

Your request body must contain an object including:

data required
Containing updates to your Specification Value object.


Example JSON request

To update a Specification Value object 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": {
        "value": "Red...ish"
    }
}

Success response

If the Specification Value 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 saved successfully.
status
The HTTP status code e.g. 200 means the object was updated successfully.
data
Contains the Specification Value object you updated.

Error responses

If the data could not be updated you will encounter a response with either a 400, 404 or 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 the Specification or Specification Value 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 Value

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

Deleting a Specification Value by its ID will remove the value from the global registry and any Product using it.

URL parameters

id required
The ID of your Specification Value object
specId 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 Media item 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.