ItemMetadata OAPI
In Surpass, you can attach metadata (known as “tags”) to items and then use these tags to organise items when authoring content, creating tests, and viewing results. Tags are made up of “tag groups” and “tag values”.
Tags are made up of categorised containers called “tag groups” that contain individual tags called “tag values”. For example, a tag group called “difficulty” might have the following tag values: “Easy”, “Medium”, and “Hard”.
Enemy relationships are also a form of metadata in Surpass; when creating an item, you can set up enemy relationships with other items. Enemy items can never appear in the same test.
The ItemMetadata OAPI is used to update tags assigned to items and their enemy relationships. For information on tag groups and tag values, read TagGroup OAPI and TagValue OAPI.
This article explains what calls can be made to the Surpass OAPI using the ItemMetadata resource.
Import this API into your Postman Workspace
Updating an item and tag value association
Send a request to the endpoint to update an item and tag value association.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header OPTIONAL |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
authorization |
header OPTIONAL |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token). |
|
content-type |
header MANDATORY |
application/json |
Determines data format of the request (JSON). |
|
content-length |
header MANDATORY |
{number} |
Determines the number of characters passed in the body of the request, where {number} is a numerical figure. This is usually automatically calculated when the request is sent. |
|
accept |
header OPTIONAL |
application/json |
Determines data format of the response (JSON). |
|
id |
path MANDATORY |
/oapi/ItemMetadata/ItemTags/{id} |
Updates item and tag value association for the specified item, where {id} is the item’s unique identifier. |
Sample request
The following request contains the minimum required request body to update an item and tag value association.
{
"tagGroups": [
{
"name": "Tag Group 1",
"tagValues": [
{
"value": "Tag Value 1"
}
]
}
]
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
tagGroups array
Contains the tag group’s information.
tagGroups/id integer
The tag group’s unique identifier.
tagGroups/name string
The tag group’s name.
tagGroups/tagCategories array
Contains the information of any tag categories the tag group is in.
tagGroups/tagCategories/id integer
The tag category’s unique identifier.
tagGroups/tagCategories/name string
The tag category’s name.
tagGroups/tagValues array
Contains the information of the tag value(s) assigned to the item.
tagGroups/tagValues/id integer
The tag value’s unique identifier.
tagGroups/tagValues/value string
The tag value.
tagGroups/tagValues/isItemSetTag Boolean
If true, the tag value is inherited from the item set.
tagGroups/tagValues/collection object
Contains the information of any tag collections the tag value is in.
tagGroups/tagValues/collection/id integer
The tag collection’s unique identifier.
tagGroups/tagValues/collection/reference string
The tag collection’s unique reference code.
tagGroups/tagValues/collection/name string
The tag collection’s name.
tagGroups/tagValues/collection/order integer
The tag collection’s position within the tag collection group.
tagGroups/tagValues/collection/isCurrent Boolean
Determines whether the tag collection is the latest tag collection (true). Only the latest tag values can be returned when searching for items in Item Search.
tagGroups/tagValues/collection/collectionGroup object
Contains the tag collection’s tag collection group information.
tagGroups/tagValues/collection/collectionGroup/id integer
The tag collection group’s unique identifier.
tagGroups/tagValues/collection/collectionGroup/reference string
The tag collection group’s unique reference code.
tagGroups/tagValues/collection/subCollection object
Contains the information of any subcollections the tag value is in.
tagGroups/tagValues/collection/subCollection/reference string
The subcollection’s unique reference code.
tagGroups/tagValues/collection/subCollection/name string
The subcollection’s name.
tagGroups/tagValues/collection/subCollection/order integer
The subcollection’s position within the subcollection group.
tagGroups/tagValues/subCollection/collectionGroup object
Contains the subcollection’s subcollection group information.
tagGroups/tagValues/subCollection/collectionGroup/id integer
The subcollection group’s unique identifier.
tagGroups/tagValues/subCollection/collectionGroup/reference string
The subcollection group’s unique reference code.
tagGroups/isDeleted Boolean
Determines whether the tag group has been deleted.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new item and tag value association’s details.
{
"response": 1,
"serverTimeZone": "GMT Standard Time"
}Updating an item’s enemy relationship
Send a request to the endpoint to update an item’s enemy relationship.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header OPTIONAL |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
authorization |
header OPTIONAL |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token). |
|
content-type |
header MANDATORY |
application/json |
Determines data format of the request (JSON). |
|
content-length |
header MANDATORY |
{number} |
Determines the number of characters passed in the body of the request, where {number} is a numerical figure. This is usually automatically calculated when the request is sent. |
|
accept |
header OPTIONAL |
application/json |
Determines data format of the response (JSON). |
|
id |
path MANDATORY |
/oapi/ItemMetadata/ItemEnemies/{id} |
Updates an enemy relationship for the specified item, where {id} is the item’s unique identifier. |
Sample request
The following request contains the minimum required request body to update an item and tag value association.
{
"enemyItems": [
{
"id": 2
}
]
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
enemyItems array
Contains the information of any items the item set has an enemy relationship with.
enemyItems/id integer
The item’s unique identifier.
enemyItems/isSectionOnly Boolean
Determines whether the enemy relationship is section-level (true) or test form-level (false).
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new item and tag value association’s details.
{
"response": 1,
"serverTimeZone": "GMT Standard Time"
}Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
Code |
Description |
|---|---|
|
400 |
Indicates one of the following issues:
|
|
401 |
The request has been sent by an unauthorised user. |
|
403 |
Item cannot be accessed. |
|
404 |
Item does not exist. |
Further reading
Read the following articles to learn how to get started with the Surpass OAPI or more about similar APIs: