Fetching resources

Uri conventions

General GET design

GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/<resource-collection>?filter=<filter-expression>

Example

GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings?filter=person in (1,2,3)

It is required to provide one or more filter properties. If no filter is present or filters are wrongfully used, the API will return a response with statuscode 400, indicating a bad request. The response will also include a corresponding error message.

Correct filter example:

...?filter=person in (1,2,3) and date ge '2024-01-01' and date le '2024-01-05'

Filter possibilities

It is expected to use the filter properties as much as possible instead of fetching a lot of data and doing post fetch processing. Rate limiting can be applied in case of extreme usages. Below you can find a list of operators that can be used in the filter query.

Operator Description Example
eq Equals kind eq 'Activity'
ge Greater than or equal date ge '2024-01-01'
le Less than or equal date le '2024-01-01'
in In collection person in (1, 2, 3)
in identifier In specific collection person in circle(2, 8) or person in org-tree(121, 122)
and Logical and person in (1,2,3) and date ge '2024-01-01'

Expand request

For certain GET endpoints, it’s possible to include additional related information in the response by using the expand query parameter. These available expansions can be found on the Swagger page under the Query options section.

You can add them to your request like this: ?expand=<InfoToExpand>

Possible expansions:

  • Usages and restrictions on activity definitions.

Example: GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/activity-structure-versions/b2347a7a-d60d-446f-b03b-7es2cc8c3281/levels/3/activity-definitions/38fc2206-b51f-434a-9c36-9e0esfc5e70e?expand=usage,restrictions

Paging

Paging is a technique used to manage and retrieve large sets of data in smaller, more manageable chunks. Instead of returning all data at once, the API provides data in pages. Each page contains a subset of the total data and a nextLink that allows you to request subsequent pages as needed.

Example 
GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings?filter=person in circle (1,2,3) and date ge '2024-01-01' and date le '2024-12-31'
200 OK

{
	"value":[
		{
			"id":21369,
			"calculatedTimeOfDayInMinutes":480,
			"isGenerated":true,
			"person":{
				"id":1
			},
			"date":"2024-01-02",
			"timeOfDayInMinutes":480,
			"kind":"InOut"
		},
		// ...
	],
	"nextLink":"/connector/protimeapi/api/v1/clockings?filter=person in circle (1,2,3) and date ge '2024-01-01' and date le '2024-12-31'&continuationToken=eyJ2YWxpZGF0aW9uSGFzaCI6MCwiaW50ZXJuYWxTZXJ2aWNlS2V5U2V0IjoiVzNzaVZHRmliR1ZCYkdsaGN5STZJbkVpTENKR2FXVnNaQ0k2SWxKRlExOU9VaUlzSWxaaGJIVmxJam8yZlYwPSJ9"
}

Delta

The Delta allows you to retrieve changes (deltas) from the Protime API since your last request. It helps reduce the volume of data by fetching only new or updated records. Check the Delta page how to use this.