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 namedmy-image-name.jpgto theimages/productssubfolder 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:
|
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.
|
links
An object containing links to traverse available search results.
|
Example JSON response
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:
|
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
|
context
|
errors
Contains an array of error objects, each will have the following properties:
|
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
|