Interact with your data programatically using the StackWave Affinity REST API
The examples in this document use the cURL program to access the API. cURL is installed by default on most Linux machines and on Windows machines beginning with Windows 10. Click here if you need to download the cURL program for other operating systems.
In this document, information in angle brackets indicates user-supplied values. For example, <subdomain> indicates your company's subdomain in the StackWave cloud.
To access the REST API, you must obtain a token from the authentication endpoint. The following call submits JSON-formatted login and password information to the REST endpoint.
curl --header "Content-Type: application/json" --request POST --data "{\"Login\":\"<username>\",\"Password\":\"<api_password>\"}" https://<subdomain>.stackwave.com/LIMS/api/v1/authenticate
This call will return a JSON-formatted response that looks like the following:
{ "token": "<token>" }
Tokens expire after thirty minutes, after which the authentication flow must be repeated to obtain a new token. Tokens must be included on all subsequent API calls using the Authorization header. The header is formatted using the bearer authorization scheme.
Authorization: Bearer <token>
For example, the following cURL call would access the REST endpoint for an antibody named Antibody-1:
curl --header "Authorization: Bearer <token>" https://<subomain>.stackwave.com/LIMS/api/v1/Antibodies/Antibody-1
This will return JSON-formatted information like the following:
{
"Schema": {
"Name": "Antibodies",
"Fields": [
{
"Name": "CreatedBy",
"Type": "string",
"Format": null
},
{
"Name": "CreatedOn",
"Type": "string",
"Format": "date-time"
},
{
"Name": "Isotype",
"Type": "string",
"Format": null
},
…
]
},
"Results": [
{
"Id": "Antibody-1",
"Name": "First Antibody",
"Description": "This is the first antibody in the system.",
"Project": "Project-1",
"Properties":
{
"CreatedBy": "scientist@stackwave.com",
"CreatedOn": "2021-10-22T14:16:00.224553-05:00",
"Isotype": "Human IgG1",
...
}
}],
NextUrl: null
}
StackWave's platform supports arbitrary properties for system entities. Affinity further allows scientists to define custom assays for uploading their data. The platform API accommodates this by providing a Schema object with assay and entity results. Schemas use the Open API type system to describe the properties of each result.
For an entity result, these properties are placed under a "Properties" key in an entity's JSON result. Every entity also includes its system ID, as well as optional user-assigned Name, Description, and Project values. The format of the result is the same whether a single entity or multiple entities are being retrieved. If a single entity is being retrieved, the Results array will contain exactly one record. If multiple entities are being retrieved, the Results array will contain zero or more records. Entities may be further filtered according to their properties:
curl --header "Authorization: Bearer <token>" https://<subomain>.stackwave.com/LIMS/api/v1/Antibodies/Antibody-1?isotype=IgG1&max-createdon=2022-06-12
Note that the “CreatedOn” property was prefixed with “max-” in the query string above. For properties that support a range search, “max-” and “min-” are both valid prefixes. For string values, pattern matching can be achieved by using the “match-” prefix. Using the same property without a prefix will test for any matching value. For example, the following cURL request retrieves a specific subset of antibodies:
curl --header "Authorization: Bearer <token>" https://<subomain>.stackwave.com/api/v1/Antibodies/Antibody-1?id=Antibody-1&id=Antibody-2&id=Antibody-3
Sequences are treated as entities and thus have the same result format as other entities in the system. However, sequence search requires a series of patterns instead of property filters. An example request that looks for proteins containing the sequence elements “STACK,” “WAVE,” or “MATCH” is provided below:
curl --header "Authorization: Bearer <token>" https://<subomain>.stackwave.com/LIMS/api/v1/sequences/proteins?pattern=STACK&pattern=WAVE&pattern=MATCH
Assay results have a similar format to entity results. If a scientist has defined an assay named "My Custom Assay", the following cURL call will retrieve results for that assay:
curl --header "Authorization: Bearer <token>" https://<subomain>.stackwave.com/LIMS/api/v1/assay-results/My%20Custom%20Assay/
{
"Assay": "My Custom Assay",
“Schema”: {
“Name”: "My Custom Assay",
"Fields": [
{
"Name": "Sample",
"Type": "string",
"Format": null
},
{
"Name": "Batch",
"Type": "string",
"Format": null
},
{
"Name": "Measurement",
"Type": "number",
"Format": “double”
},
…
]
},
"Results": [
{
"Sample": "Antibody-1",
“Batch”: “My Custom Assay-1”,
“Measurement”: 3.14,
…
}
…
],
NextUrl: https://<subomain>.stackwave.com/LIMS/api/v1/assay-results/My%20Custom%20Assay?page=2
}
In this case, more results were returned than the API-allowed limit. The permitted number was returned, and a URL that retrieves the next set of results was specified as the “NextUrl” property of the result object. This approach is used for all result sets.
NOTE: the value of the NextUrl property should not be used as a permanent hyperlink. The method of paginating the result set and the number of results returned may change from one release to the next. It is advised to always begin from the initial set and follow the NextUrl links until the entire set is retrieved.
Assay results can also be created by POSTing results to the assay results endpoint. The body of the POST message must use multipart MIME format with a form-data content disposition or the request will be rejected. The ID of the result set and the actual results to record should be sent with respective names of “id” and “results.” The “id” can be any string value while “results” must be a JSON-formatted array of results to record. Any included file or files will be associated with the recorded assay results.
The schemas for containers and lab locations are fixed. Sets of containers or lab locations therefore do not contain a “Schema” key. Containers are either wells in plates or individual tubes and vials. The presence of a “Plate” and/or “Well” property can be used to indicate a plate, while tubes and vials have a “Label” property instead.
Individual locations and containers can be added or updated by using a PUT request to the corresponding endpoint. To add or update multiple containers at once, use a PUT request to the location in which those containers are stored. This approach can also move existing containers from one location to another. Review the OpenAPI specification for the expected values in the body of each PUT request.
Access to the API is subject to certain rate limits. For an individual client, the API allows no more than 100 calls per hour, 1,000 calls per day, and 10,000 calls per week. The authentication endpoint is further rate-limited to one call per second and six per hour.
API Specification Documentation