This section provides a comprehensive guide to the Exposed APIs available in the Lab Data Automation Solution (LDAS) platform. These APIs enable external systems to integrate seamlessly with LDAS for instrument data ingestion, transformation, and file management. Access to these APIs is restricted to users with the “External API user” role. Authentication is required via a token-based mechanism, and each API call must include a valid bearer token.

The APIs covered in this guide support:

• Instrument integration via file, command, DB query, and REST modes.
• Activity generation and response retrieval.
• File upload and chunked transfer from external sources.

This guide is intended for developers and system integrators working with LDAS in regulated environments, including GxP-compliant workflows.

Getting Started: External API user authentication

Users with “External API user” role are only allowed to access exposed APIs and a token is required for this access. This authentication API provides the access token which will be used to access the exposed API by the user. Username and password of a user who has “External API user” role, should be given in the request.

📘

NOTE:

For all the exposed APIs mentioned in the following sections, the access token generated by this API should be used. The access token will expire in 5 minutes, after which this API must be called again to obtain a new access token.

{
    "username": "<username>",
    "password": "<encrypted password>"
}

In case of successful login, you receive access token and can use it to make authenticated requests. When the access token expires, you can use the refresh token to get a new one without asking the user to log in again.

Instrument Integration

Generate Activities

The following APIs are used to generate activities, which are created when a configured instrument runs and produces data.

📘

NOTE:

referenceId – an id which will be sent in the reference document of the API.

To generate activity using Instrument File

To generate an activity by uploading the instrument’s output file when the instrument is configured in File Watcher mode.

Field	Description
URL	<hostname>/api/integration/transform/file/{referenceId}
Method	POST
Request Body
Headers	Content-Type: multipart/form-data ownerName: <data owner>
Authorization	<the bearer token from the authorization>
Request parameters description	instrumentFileName – name of the instrument file with its extension. Example: instrument.csv instrumentFile – Input data received from the instrument as file.

If return response given as yes in instrument configuration, an "activityReferenceId" will be generated. If it is no in instrument configuration, the "activityReferenceId" will not be generated

To get response content for the activity

To get response content for the activity generated if the Return Response field under connection details section in Instrument’s configuration is set to true.

To generate activity with command and parameters

To generate activity with command and parameters for the instruments with RS232, OPCUA OPCHDA mode.

{
  "name": "<name>",
  "parameter": 
  {
    "<key>": "<value>"
  }
}

If return response given as yes in instrument configuration, an "activityReferenceId" will be generated. If it is no in instrument configuration, the "activityReferenceId" will not be generated

To generate activity with request parameters

To generate activity with request parameters for DB Query and Rest API modes if the instrument's parameterized field configuration is set to true.

{
  "<Key>": "<Value>"
}

If return response given as yes in instrument configuration, an "activityReferenceId" will be generated. If it is no in instrument configuration, the "activityReferenceId" will not be generated

To generate activity with the instrument configurations

To generate activity with the instrument configurations for DB Query and Rest API mode.

If return response given as yes in instrument configuration, an "activityReferenceId" will be generated. If it is no in instrument configuration, the "activityReferenceId" will not be generated

Archival

📘

NOTE:

To use the below APIs the users must either have “Archival Super User” or “Archival User” role to the folder to which the file upload is being targeted at along with “External API user” role.

File Upload from External Source

This API is first submitted with the details of the file to be uploaded – bucketName, file Size, Path to upload and the file name. The details present in the request are validated to check if the file can be uploaded. If the request is valid, a unique ID is generated for the file and is sent in the response along with the maximum chunk size that indicates the message capacity for a single chunk.Based on the maximum chunk size that is returned, the input file needs to be split into n number of chunks. For example, if a file size is 8876 bytes and the API returns 1000 as the maximum chunk size, the file needs to be spliced into 9 chunks (8 chunks with capacity of 1000 bytes and the last one with 876 bytes) and for each chunk invoke the consequent API.

{
  "fileName": "<filename.extension>",
  "fileSize": <file size>,
  "path": "<path>",
  "bucketName": "<bucket name>"
}

Upload File

This API can be used for uploading the file or to check the status of the file upload. By setting the variable “isStatusCheck” to false, file upload can be performed. Using the file ID and temp Uuid that was generated in the file details API, this API is hit to upload the file as individual chunks to LDAS. Upon receiving each chunk, the API returns the status if each chunk was received and upon receiving the last chunk, the file upload is marked as completed. By setting the variable “isStatusCheck” to true, the status of the file upload can be observed

Field	Description
URL	<hostname>/api/file/external/upload/{fileID}
Method	POST
Request Body
Headers	Content-Type: multipart/form-data
Authorization	<the bearer token from the authorization>
Request parameters description	fileId – File identifier which is generated as a response in Add file details API. fileName – Name of the file to be uploaded (Name should be given along with file extension). totalFileSize – Size of the file to be uploaded (File size KB, MB or GB should be given in 'bytes'). path – The folder path in which file has to be uploaded (Folder path can be an already existing path in archival or non-existing one). In case of non-existing folder path, folders will be created accordingly. bucketName – Name of the bucket in which the folder has to be uploaded. fileSource – Source from which the file is uploaded. Example: If the system is LIMS, then the source should be System-External.