10. CONFAB - REST API

In this section we will discuss API access for CONFAB DOE data and cloud storage. PanMo CONFAB provides read-only access via API for DOE data in the system and write-only API access to cloud storage.

NB: this API may change at any time: it is not backwards compatible and exist to provide some extra support to the users for applications not available in CONFAB at the time of writing.

10.1. Requirements

The examples show Python code with pre-requisite libraries

  • numpy,

  • pandas, and

  • requests

to be installed on your system Python or virtual environment.

10.2. Authentication

This section describes authentication system for programmatically talking to PanMo CONFAB. You can use the following code after changing the respective client_name, client_url, username, and password credentials:

# 1) Connect to the host and get your authentication token
urls = {
    f'{client_name}': f'https://{client_url}.panmo.cloud/'
}
base_url = urls[f'{client_name}']
creds = (('username', 'John_Doe'), ('password',f'{secret}'))

# 1.1) Get your auth token
client = requests.Session()
r = client.post(base_url + 'api-token/', data=creds)

# 1.2) Setup header for your client session
client.headers['Authorization'] = f'Token {r.json()["token"]}'

Throughout the session we will use the client authorized object.

10.3. DOE API

10.3.1. List DOEs

To list all the DOEs on the CONFAB system you can use the following API:

# this gets the metadata for all DOEs
r = client.get(base_url + 'confab/api/doe/')
r.json()
# example usage. The data format is a list of dictionaries
doe_list = r.json()
doe_summary = [{'pk': doe['id'], 'name': doe['projectname']} for doe in doe_list]
doe_summary

10.3.2. Retrieve Metadata for a DOE by ID

To list all the DOEs on the CONFAB system you can use the following API, where the DOE ID is 10 (primary-key):

r = client.get(base_url + 'confab/api/doe/10/')
r.json()

10.3.3. Searching

You can use following syntax in API calls for searching DOEs matching specific criteria; Syntax is ?<query_0>&<query_1>&…<query_n> where each query is in the form <field>=<value> and field is one of:

The following fields are supported with relational operators ‘==’, ‘!=’, ‘>=’, ‘>’, ‘<=’, and ‘=’.

  • substrate__abrev

  • lotid

  • vehicle__name

  • projectname

  • priority__abrev

  • projectaccountnumber

  • primaryowner__username

  • secondaryowner__username

  • create_date

  • update_date

In the following code snippet we find the DOE matching specific owners, and specific vehicle:

#search query with filters on primary owner and username
r = client.get(base_url + f'confab/api/doe/?primaryowner__username={creds[0][1]}&vehicle=6')

10.3.4. Retrieving DOE dataset

To retrieve the full data table for a specific DOE you can access it by ID as follows; in this example we access the DOE with ID 56 and display it as a Pandas DataFrame:

import pandas as pd
r = client.get(base_url + 'confab/api/doe/56/data/')
data = r.json()
df = pd.DataFrame(data)

10.4. File Upload API

Here is a simple script for uploading a file to the cloud storage bucket connected to your instance of CONFAB. Note that argparse does not need to be installed.

import requests
import argparse

def main(kwords):
    client = requests.Session()
    url = kwords.url
    # authenticate
    r = client.post(f'{url}/api-token/', data=(('username', kwords.username), ('password', kwords.password)))
    client.headers['Authorization'] = f'Token {r.json()["token"]}'
    # get the file
    file_path = kwords.storagepath
    files = dict(file=open(kwords.filepath, 'rb'))
    data = dict(file_name=kwords.filename, file_path=kwords.storagepath)
    # upload
    r = client.post(f'{url}/lims/api/file-upload/', files=files, data=data)
    print(r)
    return(r)


if __name__ == '__main__':
    parser = argparse.ArgumentParser(prog='cloud-file-upload')
    parser.add_argument('--username', required=True, action='store', help='your confab username')
    parser.add_argument('--password', required=True, action='store', help='your confab password')
    parser.add_argument('--filepath', required=True, action='store', help='path to file you wish to upload, i.e. documents/test/file.csv')
    parser.add_argument('--filename', required=True, action='store', help='uploaded file name')
    parser.add_argument('--storagepath', required=True, action='store', help='cloud storage path. If the directory does not exist it will be created')
    parser.add_argument('--url', required=True, action='store', help='url to your deployment, i.e. https://name.panmo.cloud')
    main(parser.parse_args())

10.5. Caution

NB: this API may change at any time; it is not backwards compatible and exist to provide some extra support to the users for applications not available in CONFAB at the time of writing.

NB: this API allows access to all DOEs as read-only w/o access control; so use judiciously.