Below we have listed the operations, HTTP verbs and an example URL for the TagGroup resource within the Surpass API.
|Operation||HTTP Verb||Example URL|
|Filter||GET||https://...surpass.com/api/v2/TagGroup?$filter=contains(name, 'Learning Outcomes')|
|Read (Individual by ID)||GET||https://...surpass.com/api/v2/TagGroup/|
Attributes for the TagGroup Resource
In the table below we have provided all of the attributes included in the TagGroup Resource. This includes: the attribute name, data type, if the attribute is orderable when requesting the GET method and if the attribute is available to filter when requesting the GET method.
|Attribute Name||Type||Description||Order (GET)||Filter (GET)||Unique Identifier||Mandatory for Create (POST)||Default|
|id||string||The unique identifier for the tag group.||X||X||X||X|
|href||string||The link to call the TagGroup Resource.|
|name||string||The name of the tag group in Surpass. Name will only be presented in GET response if tagTypeKey is ‘Custom’.|
|tagTypeKey||string||The category the tag group falls into. This will be one of the existing categories; ‘Learning Outcomes’, ‘Keywords’, ‘Units’ or ‘Custom’.|
|tagTypeValue||string||The tag group type. ‘Text’ or ‘Numeric’.|
|allowMultipleTags||boolean||This controls the number of tags per item. 'True' allows multiple tags per item. 'False' will restrict to one tag from this tag group per item.||true|
|authorCreation||boolean||Allows the item author to create their own tags under this tag group when 'True'.||false|
|Subject||Resource||ID or Ref can be supplied||X||X|
|type||string||The type of numeric tag. ‘Range’, ‘LessThan’, ‘GreaterThan’ or ‘Custom’.|
|lowerBoundary||The lower boundary or 'from' value in Surpass. Used when numeric tag type is 'Range'.|
|upperBoundary||integer||The upper boundary or 'to' value in Surpass. Used when numeric tag type is 'Range'.|
|boundary||The boundary for use with ‘LessThan’ or ‘GreaterThan’ numeric tag types.|
|allowDecimalPlaces||boolean||Allows decimal places with the numeric tags when 'true'. Cannot be updated with PUT request.|
- Name is the Tag Group’s display name in Surpass.
- AllowMultipleTags enables the item author to take multiple tags from this group and add them to an item. If this is set to false, only one tag from a Tag Group can be used.
- AuthorCreation determines whether authors can create their own tags during the authoring process. If false, authors can only choose from a list of pre-defined tags.
GET Request and Return
The GET TagGroup Resource can be called directly by browsing to the URL. Any required parameters such as $filter, $orderBy, $skip and $top would need to form part of the URL that is sent. Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting the GET method for the TagGroup Resource. It is important to remember that the return information will be included within the response object that forms part of the standard GET response; this is detailed in the page "Understanding the Surpass API".
Example GET request & response (JSON)
Example GET request & response (XML)
POST Request and Return
The POST TagGroup method requires the attributes listed above to be submitted as part of the body of the HTTPS request. This can be submitted in either JSON or XML format. The content-type used will need to be submitted as part of the header of the request. An example of the address, header and body of the request (for both formats) can be found below.
Example POST request & response (JSON)
Example POST request & response (XML)
PUT Request and Return
PUT Requests should reference the ID within the resource. The resource being updated should be included in the body of the request and can be sent in either JSON or XML format. Only the field you want to be updated needs to be included within the requesta and all others can be omitted; these fields will retain their current values. The content-length, content-type and Authorization will also be required in the header of the request.
All attributes included in the body of the PUT request are optional. If an attribute is omitted it will retain its current value set in the DB. You cannot update a multiple tag group to a single tag group because items might have had multiple tags assigned.
Example PUT request (JSON & XML)
To successfully call the TagValue methods, the user specified in the header of the request must have the ‘Manage Subjects’ permission in Surpass.