Folder API
A folder is an item container within a subject. Folders can hold items, item sets, and other folders, allowing for easy organisation of your test content.
The Folder API resource is used to list, retrieve, create, and update folders.
This article explains what calls can be made to the Surpass API using the Folder resource.
Import this API into your Postman Workspace
In This Article
Listing folders
Send a request to the endpoint to retrieve a list of folders. 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 MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
top |
query OPTIONAL |
/api/v2/Folder?$top={top} |
Defines number of responses to return when paging a response, where {top} is a number between 1 and 40. |
|
skip |
query OPTIONAL |
/api/v2/Folder?$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. |
|
filter |
query OPTIONAL |
/api/v2/Folder?$filter={filter} {operator} {value} |
Filters results, searching for an exact match. For an exact match: {filter} is one of id, name, subject/id, subject/reference, parentFolderId, {operator} is eq (equal to), and {value} is the string or integer the filter query looks for an exact match for in the request. |
|
orderBy |
query OPTIONAL |
/api/v2/Folder?$orderBy={attribute} |
Determines order of results, where {attribute} is one of id or name. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": 520,
"top": 10,
"skip": 0,
"pageCount": 52,
"nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/folder?$skip=10",
"prevPageLink": null,
"response": [
{
"name": "Geography Test Form June 2017 items",
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
},
"parentFolderId": 0,
"deleted": false,
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Folder/1"
},
{
"name": "Geography Test Form January 2018 items",
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
},
"parentFolderId": 0,
"deleted": false,
"id": 2,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Folder/2"
},
{
"name": "Geography Test Form June 2018 items",
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
},
"parentFolderId": 0,
"deleted": false,
"id": 3,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Folder/3"
},
{
"name": "Geography Test Form January 2019 items",
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
},
"parentFolderId": 0,
"deleted": false,
"id": 4,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Folder/4"
},
{
"name": "Geography Test Form June 2019 items",
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
},
"parentFolderId": 0,
"deleted": false,
"id": 5,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Folder/5"
},
{
"name": "History Test Form June 2017 items",
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
},
"parentFolderId": 0,
"deleted": false,
"id": 6,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Folder/6"
},
{
"name": "History Test Form January 2018 items",
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
},
"parentFolderId": 0,
"deleted": false,
"id": 7,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Folder/7"
},
{
"name": "History Test Form June 2018 items",
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
},
"parentFolderId": 478,
"deleted": false,
"id": 8,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Folder/8"
},
{
"name": "History Test Form January 2019 items",
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
},
"parentFolderId": 0,
"deleted": false,
"id": 9,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Folder/9"
},
{
"name": "History Test Form June 2019 items",
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
},
"parentFolderId": 0,
"deleted": false,
"id": 10,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Folder/10"
}
],
"errors": null,
"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 folders there are in total.
top integer
Details number of folders returned in the response.
skip integer
Details how many folders were skipped to display those in the response.
pageCount integer
Details how many pages of folders there are.
nextPageLink string
The endpoint to call the next page of folders. If null, the response is the last page of folders.
prevPageLink string
The endpoint to call the previous page of folders. If null, the response is the first page of folders.
response array
Contains the rest of the response.
name string
The folder’s name.
subject object
Contains the subject that the folder is in.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
subject/href string
The endpoint to call the subject’s information, such as /api/v2/Subject/{id} where {id} is the subject’s unique identifier.
parentFolderId integer
The parent folder’s unique identifier if the folder is in another folder.
deleted Boolean
Determines whether the folder is deleted.
id integer
The folder’s unique identifier.
href string
The endpoint to call the folder’s information, such as /api/v2/Folder/{id} where {id} is the folder’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving folder information
Send a request to the endpoint to retrieve information for a specific folder using either 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 MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path OPTIONAL |
/api/v2/Folder/{id} |
Returns information for the specified folder, where {id} is the folder’s unique identifier. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": null,
"top": null,
"skip": null,
"pageCount": null,
"nextPageLink": null,
"prevPageLink": null,
"response": [
{
"name": "Geography Test Form June 2017 items",
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
},
"parentFolderId": 0,
"deleted": false,
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Folder/1"
}
],
"errors": null,
"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 folders there are in total. This is null because the information retrieved is for a specific folder.
top integer
Details number of folders returned in the response. This is null because the information retrieved is for a specific folder.
skip integer
Details how many folders were skipped to display those in the response. This is null because the information retrieved is for a specific folder.
pageCount integer
Details how many pages of folders there are. This is null because the information retrieved is for a specific folder.
nextPageLink string
The endpoint to call the next page of folders. This is null because the information retrieved is for a specific folder.
prevPageLink string
The endpoint to call the previous page of folders. This is null because the information retrieved is for a specific folder.
response array
Contains the rest of the response.
name string
The folder’s name.
subject object
Contains the subject that the folder is in.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
subject/href string
The endpoint to call the subject’s information, such as /api/v2/Subject/{id} where {id} is the subject’s unique identifier.
subject/name string
The subject’s name. This property always returns as null.
parentFolderId integer
The parent folder’s unique identifier if the folder is in another folder.
deleted Boolean
Determines whether the folder is deleted.
id integer
The folder’s unique identifier.
href string
The endpoint to call the folder’s information, such as /api/v2/Folder/{id} where {id} is the folder’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Creating a folder
Send a request to the endpoint to create a folder.
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 MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
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 or application/xml |
Determines data format of the response, which can be either JSON or XML. |
Sample request
The following request contains the minimum required request body to create a folder.
{
"subject": {
"reference": "Subject1"
},
"name": "Geography Test Form June 2017 items"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
subject object mandatory
Contains the subject that the folder is in.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
parentFolderId integer optional
The parent folder’s unique identifier if the folder is in another folder.
position integer optional
The folder’s position within the parent folder folder if the folder is in another folder.
name string mandatory
The folder’s name.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new folder’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Folder/1",
"errors": null
}Updating a folder
Send a request to the endpoint to update a specific folder.
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 MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
content-type |
header MANDATORY |
application/json or application/xml |
Determines data format of the request, which can be either JSON or XML. |
|
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 or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path MANDATORY |
/api/v2/Folder/{id} |
Update specified folder, where {id} is the folder’s unique identifier. |
Sample request
At least one property must be updated in the request. The following request contains the minimum required request body to update a folder. Refer to the request body schema for all properties that can be updated.
{
"name": "Geography Test Form January 2018 items"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
parentFolderId integer
The parent folder’s unique identifier if the folder is in another folder.
position integer
The folder’s position within the parent folder folder if the folder is in another folder.
name string
The folder’s name.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated folder’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Folder/1",
"errors": null
}Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
Name |
Code |
Description |
|---|---|---|
|
InternalServer |
1 |
Internal server error. |
|
Unauthorized |
3 |
The request has been sent by an unauthorised user. |
|
IncorrectFieldFormat |
4 |
A field in the request has not been completed in the correct format. |
|
InaccessibleOperation |
5 |
The request has been sent by a user with invalid permissions. |
|
InaccessibleData |
6 |
The request has been sent by a user with invalid permissions. |
|
MissingBody |
7 |
There is an issue with the request body. |
|
InvalidInputParameters |
15 |
There is an issue with the path or query parameters. |
|
InvalidId |
16 |
The ID number used in the request is invalid. |
|
InvalidODataOperation |
19 |
There is an issue with the query parameters. |
|
BadRequest |
20 |
There is an issue with the /api/v2/Folder?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
|
FolderDoesNotExist |
65 |
Specified folder does not exist. |
Further reading
Read the following articles to learn more about similar APIs, how to get started with the Surpass API v2, and how to get the best out of this reference documentation: