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
User-Agent Header Required
All API requests MUST include a User-Agent header.
The User-Agent header is required for traceability, allowing us to track the source of API calls and provide targeted support when issues arise.
User-Agent Best Practices
We highly recommend using a different User-Agent per service that uses the Protime API. This allows for better monitoring, debugging, and support.
Recommended format: "ServiceName/Version (Company Name)"
Example scenario: Customer “ABC Inc” develops 2 custom services:
- PeopleSyncService
- ActivityFetchingService
Recommended User-Agent values:
"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 | "PeopleSyncService/v1 (ABC Inc)" |