General specs
Versioning
The API-version is embedded in the URI (…/api/v1/…). In general we intend to keep the API frozen at a version, and will do everything we can to evolve in a backwards compatible way.
Uri conventions
https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/<resource-collection>/<resource-id>
<tenant>discriminator identifying the tenant<resource-collection>a noun, plural, e.g.clockingsorclocking-requests<resource-id>typically an integer or Guid, identifying a single resource in the collection
Naming things
- Resource names use kebab-casing, e.g. clocking-requests
- Resource-collection will be a noun, and will be plural
Request headers
It is required to send a custom, agreed-upon, User-Agent header. This is for traceability reasons. It allows us to track where calls come from, and to point to the right service for the customer if there is a problem.
We highly recommend to use a different User-Agent per service that uses the Protime API.
E.g. suppose a customer “ABC Inc” develops 2 custom services:
- PeopleSyncService
- ActivityFetchingService
We would recommend following user agents:
- “PeopleSyncService/v1 (ABC Inc)”
- “ActivityFetchingService/v1 (ABC Inc)”
Header examples
| Header key | Applies to | Example | Condition |
|---|---|---|---|
| Accept | Request | application/json |
|
| Authorization | Request | Bearer eyJ...Uc |
|
| Content-Type | Request/Response | application/json |
|
| Content-Length | Request/Response | 1024 |
|
| ETag | Response | "46ab44" |
|
| If-Match | Request | "46ab44" |
|
| If-None-Match | Request | "46ab44" |
|
| Location | Response | /connector/protimeapi/api/v1/clockings/76547 |
201 Created |
| Operation-Location | Response | /connector/protimeapi/api/v1/status-monitor/clockings/931 |
202 Accepted |
| Retry-After | Response | 60 |
|
| User-Agent | Request | "Partner-product-name/1.0 (Partner-name)" |