TagValue 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”.
The TagValue OAPI resource is used to list and retrieve tag values. For information on tag groups, read TagGroup OAPI. To learn how to add tag values to items, read ItemMetadata OAPI.
This article explains what calls can be made to the Surpass OAPI using the TagValue resource.
Import this API into your Postman Workspace
In This Article
Listing tag values
Send a request to the endpoint to retrieve a list of tag values. Refer to the available parameters to influence the response. No request body is required.
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). |
|
accept |
header OPTIONAL |
application/json |
Determines data format of the response (JSON). |
|
fieldsNames |
query OPTIONAL |
/oapi/TagValue?fieldsNames={fieldsNames} |
Includes additional properties in the response not returned as standard, where {fieldsNames} is one of the following properties returned when retrieving information for a specific tag value: tagGroup. |
|
filter |
query OPTIONAL |
/oapi/TagValue?filter={filter} {operator} {value} |
Filters results, searching for an exact match or for the data to contain a defined value. For an exact match: {filter} is one of id, value, deleted, tagGroup.id, tagGroup.name, tagGroup.deleted; {operator} is eq (equal to); and {value} is the string, Boolean, or integer the filter query looks for an exact match for in the request. For a greater than query: {filter} is id, tagGroup.id; {operator} is ge (greater than); and {value} is the integer the filter looks for more than in the request. For a less than query: {filter} is id, tagGroup.id; {operator} is le (less than); and {value} is the integer the filter looks for less than in the request. |
|
filterGrouping |
query OPTIONAL |
/oapi/TagValue?filter={filter} {operator} {value}&filter={filter} {operator} {value}&filterGrouping={integer} {operator} {integer} |
Used to create different Boolean combinations when multiple properties are joined within a filter query parameter. See filter above. Each {integer} represents a respective filter starting at 0, which are then combined using an AND or OR Boolean {operator}.
EXAMPLE: The endpoint /oapi/TagValue?filter=id le 10=deleted eq true&filterGrouping=0 OR 1 would return both tag values with a unique identifier less than 10 (0) and deleted tag values (1).
TIP: More than two filter parameters can be combined, for example you might group three filters as follows: 0 AND 1 OR 2.
|
|
orderBy |
query OPTIONAL |
/oapi/TagValue?orderBy=fieldName={fieldName} |
Determines order of results, where {fieldName} is one of id, value, deleted. |
|
take |
query OPTIONAL |
/oapi/TagValue?take={take} |
Defines number of responses to return when paging a response, where {take} is a number between 1 and 100. |
|
skip |
query OPTIONAL |
/oapi/TagValue?skip={skip} |
Defines how many responses to skip when paging a response, where {skip} is a number that should not exceed the total number of responses. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in JSON format as requested.
{
"count": 6001,
"top": 10,
"skip": 0,
"totalPages": 301,
"nextPageLink": "https://{your Surpass instance}.surpass.com:443/oapi/TagValue?Skip=20&Take=10",
"previousPageLink": null,
"results": [
{
"id": 1,
"value": "Knowledge of European Geography",
"deleted": false
},
{
"id": 2,
"value": "Knowledge of American History",
"deleted": false
},
{
"id": 3,
"value": "Knowledge of Chemical Structures",
"deleted": false
},
{
"id": 4,
"value": "Knowledge of English Literature",
"deleted": false
},
{
"id": 5,
"value": "Knowledge of Renaissance Art",
"deleted": true
},
{
"id": 6,
"value": "Knowledge of French Cuisine",
"deleted": false
},
{
"id": 7,
"value": "Knowledge of Social Sciences",
"deleted": false
},
{
"id": 8,
"value": "Knowledge of Abrahamic Religions",
"deleted": false
},
{
"id": 9,
"value": "Knowledge of Natural Philosophy",
"deleted": false
},
{
"id": 10,
"value": "Knowledge of Political Systems",
"deleted": false
}
],
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many tag values there are in total.
top integer
Details number of tag values returned in the response.
skip integer
Details how many tag values were skipped to display those in the response.
totalPages integer
Details how many pages of tag values there are.
nextPageLink string
The endpoint to call the next page of tag values. If null, the response is the last page of tag values.
previousPageLink string
The endpoint to call the previous page of tag values. If null, the response is the first page of tag values.
results array
Contains the rest of the response.
id integer
The tag value’s unique identifier.
value string
The tag value’s name in Surpass.
deleted Boolean
Determines whether the tag value is deleted (true).
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving tag value information
Send a request to the endpoint to retrieve information for a specific tag value using its ID. No request body is required.
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). |
|
accept |
header OPTIONAL |
application/json |
Determines data format of the response (JSON). |
|
id |
path OPTIONAL |
/oapi/TagValue/{id} |
Returns information for the specified tag value, where {id} is the tag value’s unique identifier. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in JSON format as requested.
{
"response": {
"id": 1,
"value": "Knowledge of European Geography",
"deleted": false,
"tagGroup": {
"id": 1,
"name": "Tag Group 1",
"href": "https://{your Surpass instance}.surpass.com/oapi/TagGroup/1",
"deleted": false
}
},
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
results object
Contains the rest of the response.
id integer
The tag value’s unique identifier.
value string
The tag value’s name in Surpass.
deleted Boolean
Determines whether the tag value is deleted (true).
tagGroup object
Contains the tag group that contains the tag value.
tagGroup/id integer
The tag group’s unique identifier.
tagGroup/name string
The tag group’s name.
tagGroup/href string
The endpoint to call the tag group’s information, such as /oapi/TagGroup/{id} where {id} is the tag group’s unique identifier.
tagGroup/deleted Boolean
Determines whether the tag value is deleted or not.
serverTimeZone enumeration
The timezone of the server sending the response.
Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
Code |
Description |
|---|---|
|
400 |
There is an issue with the query parameters. |
|
401 |
The request has been sent by an unauthorised user. |
|
403 |
Tag value cannot be accessed. |
|
404 |
Tag value does not exist. |
Further reading
Read the following articles to learn how to get started with the Surpass OAPI or more about similar APIs: