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:

For EDRN, https://edrn-labcas.jpl.nasa.gov
For NIST, https://labcas.jpl.nasa.gov/nist

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

HTTP Basic authentication with a username and password.
JSON Web Token (JWT) bearer authorization by first passing a username and password with HTTP Basic authentication to the /auth endpoint to generate a JWT, which can then be passed all other endpoints.

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.

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 GET "{{base_url}}/data-access-api/auth"

GET %7B%7Bbase_url%7D%7D/data-access-api/auth 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 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/datasets/list?q=*:*&fq&start=0&rows=1"

GET %7B%7Bbase_url%7D%7D/data-access-api/datasets/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/files/list?q=*:*&fq&start=0&rows=1"

GET %7B%7Bbase_url%7D%7D/data-access-api/files/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:

◀️ Previous page — Next page ▶️