Standard Headers

Communication with the service APIs requires the transfer of certain ‘standard’ headers during the interaction.

The headers are described below:

User-Agent

Header that allows identification of the server, network, application, operating system, and version of the requester. (e.g. Lynfa/5.0 (Windows NT x.y; rv:10.0) Paghe/1.0)

User-Agent = 'Lynfa/5.0 (Windows NT 10.0; rv:10.0) Paghe/1.0'

X-App-Name

Caller application name – TeamSystem applications use an internal naming convention so they can be recognized within the system. In this case, use the registered identification code (e.g. TSXYZ).

In the case of use by third-party applications, please use an abbreviated name that clearly refers to the calling application.

X-App-Name = 'TSXYZ'

X-App-Version

Version of the application making the call (e.g. 1.0.2)

X-App-Version = '1.0.2'

X-Request-ID

Unique identifier of the request. It is a unique string that should uniquely identify the request made to the service. It is recommended to use a GUID / UUID.

X-Request-ID = '550e8400-e29b-41d4-a716-446655440000'

X-Correlation-ID

Correlation identifier for multiple requests. This identifier is a string that allows multiple distinct requests to be correlated with one another when they are linked by a context known to the client.

For example, if executing a client operation requires making N distinct calls to complete a task, it is possible to use a task identifier as the correlation-id and then distinguish each individual call using the request id.

Alternatively, the correlation id can be used to link calls that occur when services invoke other services ‘in cascade’. By propagating the correlation id across services, support will be able to trace the chain of calls performed and more easily identify any issues.

X-Correlation-ID = 'task-123e4567-e89b-12d3-a456-426614174000'

X-Item-ID

Identifier of the TS platform item that is performing the operation. For example, you can use the UUID from the company registry of the holder.

// example 1
X-Item-ID = 'holder uuid'
// example 2
X-Item-ID = '123e4567-e89b-12d3-a456-426614174000'

X-Manager-ID

Identifier of the TS platform item that manages the item provided in the X-Item-ID header. For example, it is the same value if the company is acting for itself, or you can use the UUID from the company registry of the submitter/study in case of studies use cases.

// example 1
X-Manager-ID = 'submitter uuid'
// example 2
X-Manager-ID = '123e4567-e89b-12d3-a456-426614174000'

X-User-ID

Identifier of the TS platform user performing the operation. For example, it could be the email identifier corresponding to the authentication token or the email of the operator performing the operation.

X-User-ID = 'submitter-email@submitteremail.com'

X-Forwarded-For

Indication of the IP address of the client that originated the initial call. This header allows, if needed, the propagation of the client IP identification when services call each other in cascade.

X-Forwarded-For = '203.0.113.195'

Accept-Language

Indication of the language in which the client prefers to receive response information. (This header is currently not significant for TS Archive but is included for consistency with services exposed by Teamsystem.)

Accept-Language = 'it-IT'