Reference
General specs

General specs

This page documents the versioning scheme, URI conventions, and request headers for the Protime API.

Versioning

The API version is embedded in the URI (.../api/v1/...). The API is frozen at a version and evolves in a backwards-compatible way.

URI conventions 

https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/<resource-collection>/<resource-id>
Segment Description
<tenant> Discriminator identifying the tenant
<resource-collection> A noun, plural, e.g. clockings or access-clockings
<resource-id> Typically an integer or GUID, identifying a single resource in the collection

Naming conventions

  • Resource names use kebab-casing, e.g. access-clockings.
  • Resource collections are always a noun and always 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 Protime to track the source of API calls and provide targeted support when issues arise.

User-Agent format

Each service that consumes the Protime API is expected to send a distinct User-Agent value. This enables per-service monitoring, debugging, and support.

Format: "ServiceName/Version (Company Name)"

Example: Customer “Acme Corp” operates two services – PeopleSyncService and ActivityFetchingService.

Service User-Agent value
PeopleSyncService "PeopleSyncService/v1 (Acme Corp)"
ActivityFetchingService "ActivityFetchingService/v1 (Acme Corp)"

Header reference

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
Retry-After Response 60
User-Agent Request "PeopleSyncService/v1 (Acme Corp)"

See also

Authentication