Folder Resource
Folder Resource
Below we have listed the operations, HTTP verbs and an example URL for the Folder resource within the Surpass API.
| Operation | HTTP Verb | Example URL |
|---|---|---|
| List | GET | https://...surpass.com/api/v2/Folder/ |
| Filter | GET | https://...surpass.com/api/v2/Folder?$filter=name eq ‘JamesTest’ |
| Read (Individual by ID) | GET | https://...surpass.com/api/v2/Folder/1 |
| Create | POST | https://...surpass.com/api/v2/Folder/ |
| Update | PUT | https://...surpass.com/api/v2/Folder/1 |
Attributes for the Folder Resource
Within the table below we have provided all of the attributes included in the Folder 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) | Available Operators (GET) | Unique Identifier | Mandatory for Create (POST) |
|---|---|---|---|---|---|---|---|
| Id | Int | The unique identifier for the folder. Unable to POST | X | X | eq, lt, le, gt, ge, ne | X | N/A |
| Name | string | The name of the folder. | X | X | eq, ne, contains | X | |
| Subject | Resource | The subject that the folder will belong to. ID or Ref can be supplied. Unable to PUT. | X | X | eq, contains | X | |
| Parent folder id | Int | The ID of the parent folder. | X | X | eq, lt, le, gt, ge, ne | ||
| Position | Int | Refers to the position of this folder within the parent folder. |
The GET Folder 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 Folder 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 and response (JSON)
Example GET request and 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.
Example POST request and response (JSON)
Example POST request and response (XML)
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 the position property as part of the POST or PUT request.
PUT Request and Return
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 reference is required as part of the URL, all fields are optional and Subject cannot be supplied in the PUT request.
Required Permissions
To successfully call the Folder methods, the user specified in the header of the request must have the "Item Writer", “Item Reviewer” or “Item Publisher” role in Surpass.