|Operation||HTTP Verb||Example URL|
|Filter||GET||https://...surpass.com/api/v2/ItemSet?$filter=name,eq ‘Item Set 1’|
|Read (Individual by ID)||GET||https://...surpass.com/api/v2/ItemSet/1|
Within the table below we have provided all of the attributes included in the Item Set 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.
|Property Name||Type||Description||Default Value||Filterable (GET)||Mandatory (POST)|
|subject||object||The subject that the Item Set belongs to.||n/a||x||x|
|subject / id||int||The id of the subject the Item Set belongs to.||x|
|subject / reference||string||The reference of the subject the Item Set belongs to.||x|
|subject / href||string||The Request URL for the subject the Item Set is part of.||n/a||n/a||n/a|
|parentFolderId||int||The id of the parent folder the Item Set belongs to.||root folder||x|
|position||int||The position of the folder within the parent folder.||0|
|name||string||The name of the Item Set.||n/a||x|
|allowRandomisation||boolean||If 'true', the order of the items in the item set can be randomised in 'Test Creation'.||false|
|locked||boolean||If 'true', the order of items in the item set cannot be rearranged.||false|
|items||collection||A collection of items within the Item Set.||n/a|
|items / type||enumeration||The question type of the item within the Item Set.|
|items / id||int||The id of the item within the Item Set.|
|items / href||string||The request URL of the item within the Item Set.|
|id||int||The unique id of the Item Set.||n/a||n/a|
|href||string||The request URL of the Item Set.||n/a||n/a|
|sharedWith||resource||The item set has been shared with a subject master list.||n/a|
|sharedWith / id
||int||The id of the subject master list the item set has been shared with.||n/a|
|sharedWith / reference
||string||The reference of the subject master list.||n/a|
|sharedWith / href
||string||The URL to GET the subject the item set has been shared with.||n/a|
||object||The item set is part of a standard item list.||n/a|
|standardLists / id
||int||The id of the standard list the item set belongs to.||n/a|
|standardLists / reference
||string||The reference of the standard list.||n/a|
|standardLists / href
||string||The URL to GET the standard list the item set belongs to.||n/a|
|owner||object||The owner of the item set.||Will default to the user who created the item set if left blank.||n/a|
|owner / id||int||The id of the user who is the item owner.||n/a||n/a|
|owner / reference||string||The reference of the user who is the item owner.||n/a||n/a|
|owner / href||string||The URL to GET the user the item set belongs to.||n/a||n/a|
The GET Item set 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 Item Set resource.
Example GET request & response (JSON)
Example GET request & response (XML)
POST Request and Return
The POST Folder 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.
- If "parentFolderId" is omitted this will be created in the root directory. Subject and Name are mandatory.
- "position" refers to the position of the folder in the parent folder. If a number is supplied that is higher than the number of folders/items the folder will be placed last.
- 0 refers to the root directory when supplied in the parent folder id property and also indicates the first position when supplying position property as part of the POST or PUT request.
PUT Requests should reference the ID of the resource. The properties being updated should be included in the body of the request and can be sent in either JSON or XML format. All properties are optional within the PUT request so any omitted proprieties will be unchanged. The "Authorization" header will also be required in the request for it to be successful.
The body of the request should be formed in the same way as the POST request and the response also returns the same information. An example of this can be found in the “POST Request and Return” section above. The only differences between the POST and PUT requests is that the ID is required as part of the URL, all fields are optional and Subject cannot be supplied in the PUT request.
To successfully call the Item Set methods, the user specified in the header of the request must have the "Item Writer", “Item Reviewer” or “Item Publisher” permission in Surpass depending on the status of the items within the set.