LabCAS API

Download API: Postman (JSON) OpenAPI (YAML)

API Documentation

This is a collection of ReST endpoints supported by LabCAS, the software that powers the Data Commons of the Early Detection Research Network (EDRN) and the National Institute of Standards and Technologies (NIST).

The base URLs are:

Note that all endpoints require authentication to function. This can be provided using either:

  • HTTP Basic authentication with a username and password (if supported by your consortium)

  • JSON Web Token (JWT) bearer authorization (preferred)

    • The source of your JWT may vary depending on consortium; for EDRN you use the /auth endpoint to generate one. For NIST, you may be required to use your SSO.

👉 Note: When using this API collection under Postman, use the Token Service → Authentication request first to generate a JWT that can be used with other requests. The username and password must appear in the Postman environment.

API detail

Token Service

The Token service has a single endpoint whose responsibility is to generate JSON Web Tokens (JWTs) for use with the other ReST API endpoints, track sessions, and invalidate a session when a user wishes to log out.

👉 Note: these endpoints may not be in use, depending on the consortium’s installation of LabCAS.

Authentication

This endpoint generates a JSON Web Token (JWT) given a valid username and password with HTTP Basic authentication. The JWT can then be used as the bearer authorization in future ReST endpoint calls.

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "username={{username}}&password={{password}}" "{{base_url}}/data-access-api/auth"
POST %7B%7Bbase_url%7D%7D/data-access-api/auth HTTP/1.1
Host: 
Content-Type: application/x-www-form-urlencoded

username={{username}}&password={{password}}

Logout 

curl -X GET "{{base_url}}/data-access-api/logout?sessionID={{session_id}}"
GET %7B%7Bbase_url%7D%7D/data-access-api/logout?sessionID={{session_id}} HTTP/1.1
Host:

User Data Service

The endpoints here serve to create/update, read, and delete user data. User data in LabCAS refers to “favorites”:

  • Favorite data collections
  • Favorite datasets
  • Favorite files

Create

The “create” endpoint creates (or updates) user data (favorite data collections, favorite datasets, and favorite files). Note you can create only your own user data, i.e., the username of the id parameter must match the username in the HTTP Basic Authentication or in the JWT bearer authorization header.

The payload for this request is a JSON dictionary with the following fields:

  • id which must also match the id query parameter
  • FavoriteCollections which is a list of strings naming each favorite data collection
  • FavoriteDatasets which is a list of strings naming each favorite dataset
  • FavoriteFiles which is a list of strings naming each favorite file
curl -X POST -d '{
    "id": "{{username}}",
    "FavoriteCollections": [],
    "FavoriteDatasets": [],
    "FavoriteFiles": []
}' "{{base_url}}/data-access-api/userdata/create"
POST %7B%7Bbase_url%7D%7D/data-access-api/userdata/create HTTP/1.1
Host: 

{
    "id": "{{username}}",
    "FavoriteCollections": [],
    "FavoriteDatasets": [],
    "FavoriteFiles": []
}

Read

This endpoint retrieves any user data saved under the given id. Note that the id must match the username in the HTTP Basic authentication or in the JWT bearer authorization.

The JSON return value of this call is not the same as tha payload used in the create call. Rather, it is a raw Solr query response in JSON format, which includes search results metadata, which can be ignored. The real results are in the zeroth element of the docs key.

curl -X GET "{{base_url}}/data-access-api/userdata/read?id={{username}}"
GET %7B%7Bbase_url%7D%7D/data-access-api/userdata/read?id={{username}} HTTP/1.1
Host:

Delete

Deletes the user data associated with the given id. Note that the username given in the id must match the username in either the HTTP Basic authentication or the JWT bearer authorization.

The return value is a JSON payload giving Solr metadata after deleting the data.

curl -X POST "{{base_url}}/data-access-api/userdata/delete?id={{username}}"
POST %7B%7Bbase_url%7D%7D/data-access-api/userdata/delete?id={{username}} HTTP/1.1
Host:

Download Service

The Download Service contains a single ReST endpoint that support the downloading of individual files from the Data Commons.

Download

The download endpoint begins the transfer of a data file over HTTP. The file to be downloaded is named via its identifier, or id.

curl -X GET "{{base_url}}/data-access-api/download?id={{file_id}}"
GET %7B%7Bbase_url%7D%7D/data-access-api/download?id={{file_id}} HTTP/1.1
Host:

List Service

Endpoints in the list service return lists of files that match given criteria. These lists are newline-separated strings of URLs that use refer to the Download Service for file data retrieval.

Collections

The Collections List endpoint returns a list of files found within collections, one per line.

curl -X GET "{{base_url}}/data-access-api/collections/list?q=*:*&fq&start=0&rows=1"
GET %7B%7Bbase_url%7D%7D/data-access-api/collections/list?q=*:*&fq&start=0&rows=1 HTTP/1.1
Host:

Datasets

The Datasets List endpoint returns a list of files found within datasets, one per line.

curl -X GET "{{base_url}}/data-access-api/collections/list?q=*:*&fq&start=0&rows=1"
GET %7B%7Bbase_url%7D%7D/data-access-api/collections/list?q=*:*&fq&start=0&rows=1 HTTP/1.1
Host:

FIles

The Files List endpoint returns a list of files matching given query criteria, one per line.

curl -X GET "{{base_url}}/data-access-api/collections/list?q=*:*&fq&start=0&rows=1"
GET %7B%7Bbase_url%7D%7D/data-access-api/collections/list?q=*:*&fq&start=0&rows=1 HTTP/1.1
Host:

Query Service

The Query Service endpoints enable you to send queries to the Data Commons’ Solr service and receive search results (metadata) back.

Collections

Search for and retrieve data collections in LabCAS. This request is passed onto Solr which handles the metadata within the Data Commons.

curl -X GET "{{base_url}}/data-access-api/collections/select?q=*:*&wt=json&indent=true&rows=10&sort=id asc&start=0"
GET %7B%7Bbase_url%7D%7D/data-access-api/collections/select?q=*:*&wt=json&indent=true&rows=10&sort=id asc&start=0 HTTP/1.1
Host:

Datasets

Search for and retrieve datasets in LabCAS. This request is passed onto Solr and accepts all Solr query parameters.

curl -X GET "{{base_url}}/data-access-api/datasets/select?q=*:*&wt=json&indent=true&rows=10&sort=id asc&start=0"
GET %7B%7Bbase_url%7D%7D/data-access-api/datasets/select?q=*:*&wt=json&indent=true&rows=10&sort=id asc&start=0 HTTP/1.1
Host:

Files

Search for and retrieve data files in LabCAS. This request is passed onto Solr and accepts all Solr query parameters. This does not return the actual file data, but metadata about the files.

curl -X GET "{{base_url}}/data-access-api/files/select?q=*:*&wt=json&indent=true&rows=10&sort=id asc&start=0"
GET %7B%7Bbase_url%7D%7D/data-access-api/files/select?q=*:*&wt=json&indent=true&rows=10&sort=id asc&start=0 HTTP/1.1
Host: