Common properties for RESTFul apis
- Thomas Hellstrøm (Unlicensed)
Introduction
HRMTS provides a set of RESTFul Web Service to retrieve various information through Third Party Systems. The function of this Web Service is restricted to read-only.
Requirements
Following configuration in the System is required before the Web Service can be used:
- Enable the web service in Customer’s account.
- Configure an API key.
- Configure IP address filter.
- Use HTTPS.
HRMTS Support can assist the Customer in this configuration
Success Response Format
Successful responses from all Web Service methods follow a common convention. The HTTP status code for all successful responses is 200.
Root Element
The root element describes the type of data being returned. In the example above, the candidate list is being returned.
Execution Time
The node for execution time indicated the time used on the server to deliver this data. This data is included for the benefit of both Customer and HRMTS. The customer can keep a log of average delivery time for their typical method calls and report in case of inconsistencies. Also, they can see which method calls are expensive so that they can call the methods in a more optimized way. HRMTS can benefit from these values when debugging or extending the Web Service and during releases.
Customer
The node for customer repeats the basic customer information that is supplied in the call to Web Service method.
Counts
The node for counts provide information on various counts on the data that is delivered. This information is useful in implementing paging support.
Node | Description |
Search Count | Number of elements that match the criteria. May be more than what is delivered in the current call. |
Skip Count | Number of elements that match the criteria and are skipped or jumped. |
Take Count | Number of elements that match the criteria and are included in the results. |
Total Count | Total number of elements available on the server. In the example above, the value indicates 106 candidates in the Customer account. |
Sort
The node for sort indicates the sorting criteria used in the results.
Node | Description |
Field | The field on which the results are sorted by. |
Direction | The direction of sort – ascending or descending. |
Error Response Format
Failed responses from all Web Service methods follow a common convention. The HTTP status code for all successful responses is according to the error that has occurred, e.g. 500.
Root Element
The root element describes the transaction status.
Status Code
Represents the HTTP status code.
Status Description
Describes the actual error that occurred on the server.
Important to Know
Depending on the query string parameters, the Web Service methods may return one or more data objects. Each data object is divided into two parts. The first part consists of basic properties such as id, name etc., while the second part consists of all other detailed properties.
When more than one data objects are returned by a Web Service method, only the basic properties are included in the results. The detailed properties are not included to make the delivery lightweight. Only when a single data object is returned, then the detailed properties are also included.
Common Query String Parameters
All Web Service methods accept query string parameters to know type and amount of data to return. Each method has its dedicated parameters, while following parameters are common for all methods.
Skip
| Parameter | skip |
|---|---|
| Description | Send this paging parameter to define how many data objects to skip from the beginning of the list once the search and filter criteria are applied. |
| Value type | Integer |
Default value | 0 |
| Sample | …/?skip=1 |
Take
| Parameter | take |
|---|---|
| Description | Send this paging parameter to define how many data objects to include in the returned list once the search and filter criteria are applied. Take is limited to 100 in all API methods. |
| Value type | Integer |
Default value | 25 |
| Sample | .../?take=10 |
Sort By
| Parameter | sortby |
|---|---|
| Description | Send this parameter to sort the list with a specific property of the data object. Only limited number of properties are supported for sorting. |
| Value type | string |
Default value | "Id" |
| Sample | .../?sortby=id |
Sort Ascending
| Parameter | sortasc |
|---|---|
| Description | Send this parameter to sort the list in the ascending order with value defined in “sortby” |
| Value type | Boolean |
Default value | True |
| Sample | .../?sortasc=1 |
UI Culture
| Parameter | uiculture |
|---|---|
| Description | Send this parameter to get the localized text for the values of dropdown lists, e.g. education etc. The available languages are:
|
| Value type | text |
Default value | Default customer language |
| Sample | .../?uiculture=en |
Department Id
| Parameter | depid |
|---|---|
| Description | Send this parameter to filter the list with a single department id. |
| Value type | Integer |
Default value | Root department id |
| Sample | …/?depid=1 |
Include Sub Departments
| Parameter | incsub |
|---|---|
| Description | Send this parameter to include the sub departments in filtering of data objects. |
| Value type | Boolean |
Default value | False |
| Sample | .../?incsub=1 |