API Instructions for API v1

Command Line API

Acquiring an API Key

In order to query the API, you will need to have an API Key. Currently, API access is private: if you don't have a key, you will have to request one.

If you would like a key, please reach out to our team:

James (Jim) Griffioen: griff@netlab.uky.edu
Vikram Gazula: gazula@uky.edu
Sandesh Lamichhane: sla302@uky.edu

Using the API

The URL for accessing our API is: https://sds-ara-api.access-ci.org/api/v1

The basic syntax for querying the API is as follows:

Query RP:
curl https://sds-ara-api.access-ci.org/api/v1 -X POST -H "Content-Type: application/json" -H "X-API-Key: your_api_key"
-d '{"rps": ["rp_name"]}'
Query Software:
curl https://sds-ara-api.access-ci.org/api/v1 -X POST -H "Content-Type: application/json" -H "X-API-Key: your_api_key"
-d '{"software": ["software_name"]}'
Query Software on RP:
curl https://sds-ara-api.access-ci.org/api/v1 -X POST -H "Content-Type: application/json" -H "X-API-Key: your_api_key"
-d '{"software": ["software_name"], "rps": ["rp_name"]}'

Note that all query responses are sorted alphabetically by software name.

Here is a breakdown of this command:

Command Description Required/Optional
curl (Client for URL) is a tool for transferring data through network protocols. Wget and other similar commands will also work. Required
https://sds-ara-api.access-ci.org/api/v1 This is the 'Path' to the API. Required
-H "Content-Type: application/json" Informs the api server the datatype for your request. You will never have to change this Required
-H "X-API-Key: your_api_key"{API_KEY} Once you've obtained an API Key from us, you will need to replace 'your_api_key' your actual key each time you query the API.
Without a valid key, your request will be denied.
It is also case-sensitive. 		Required
"rps": ["rp_name"] This is the data you will be requesting from the api server. Replace 'rp_name' with the group id(s), resource id(s) or resource name of the Resource Provider you are retrieving information for. This should be formatted as: "rp_group_id1", "rp_group_idn"

For example, if you want to grab all software on anvil and ookami, your query will be: -d '{ "rps": ["anvil.purdue.access-ci.org", "ookami.sbu.access-ci.org"] }'

Here is how you would make the same query using rp names: -d '{ "rps": ["anvil", "ookami" ] }'

The values are not case sensitive, i.e. 'anvil' and 'ANVIL' will be treated the same. 		Required
"software": ["software_name"] This is the data you will be requesting from the api server. Replace 'software' with the name of you software you are requesting data for. This should be formatted as: "software_name1", "software_namen"

For example, if you want to grab information for gaussian and abacas, your query will be: "software": ["gaussian", "abacas"]

The values are not case sensitive, i.e. 'Gaussian' and 'gaussian' will be treated the same. 		Required

By default, queries extract all the information about a software. However, if you are only interested in certain fields, there are some optional flags you may add to your query.

Flag Description Required/Optional
"columns": ["column_name"] Include this if you are only interested in getting data from certain columns.
Format as: -d '{ "software": ["software_name"], "columns": ["column_name1", "column_name2"] }'

To grab only the RP name and software name for all software on Anvil: -d '{ "rps": ["anvil"], "columns": ["rp_name", "software_name"] }'

NOTE: the rp_software and software_name columns are always shown. 		Optional
"exclude": true/false As an alternative, if you are interested in all but a few specific columns, you can exclude them instead.
Default is false
Format as: -d '{ "rps": ["anvil"], "columns": ["rp_name", "software_name"], "exclude": true}'

To grab all information except software_description and ai_software_description on Anvil: -d '{ "rps": ["anvil"], "columns": ["software_description", "ai_software_description"], "exclude": true}' 		Optional
"fuzz_software": true/false Flag to use fuzzy search to find matching software name
Default is false
Format as: -d '{ "software": ["search_term"], "fuzz_software":true }'

To perform a fuzzy search for the term blas: -d '{ "software": ["blas"], "fuzz_software": true }' This will return all entries for software that contain "blas", such as: blas, blast+, kblas-gpu, openblas, etc.

Note that all data returned will be sorted alphabetically based on software name in the following order: exact matches -> starts with -> contains -> other 		Optional
"fuzz_rp": true/false Flag to use fuzzy search to find matching rp_name, rp_group_id, or rp_resource_id
Default is false
Format as: -d '{ "rps": ["search_term"], "fuzz_rp":true }'

To perform a fuzzy search for the term "ncsa": -d '{ "rps": ["ncsa"], "fuzz_software": true }'
This will return all entries for rp_name, rp_group_id, or rp_resource_id that contain "ncsa", such as: deltaai.ncsa.access-ci.org, delta.ncsa.access-ci.org 		Optional

By default, the api aggregates data by software and so there will only be on item per software returned by the api.


"data": [
    {
    "software_name": "tensorflow",
    "rps": {
        "aces.tamu.access-ci.org": {
        "rp_name": "aces",
        "rp_resource_id": [
            "aces.tamu.access-ci.org"
        ]
        },
        "bridges2.psc.access-ci.org": {
        "rp_name": "bridges-2",
        "rp_resource_id": [
            "bridges2-gpu.psc.access-ci.org",
            "bridges2-rm.psc.access-ci.org",
            "bridges2-em.psc.access-ci.org",
            "bridges2-gpu-ai.psc.access-ci.org"
        ]
        },
        "delta.ncsa.access-ci.org": {
        "rp_name": "delta",
        "rp_resource_id": [
            "delta-cpu.ncsa.access-ci.org",
            "delta-gpu.ncsa.access-ci.org"
        ]
        },
        "anvil.purdue.access-ci.org": {
        "rp_name": "anvil",
        "rp_resource_id": [
            "anvil-ai.purdue.access-ci.org",
            "anvil.purdue.access-ci.org",
            "anvil-gpu.purdue.access-ci.org"
        ]
        }
    }
    }
]

If you would like the data to be aggregated by rp_group_id (i.e. resource each rp group will have its own entry for each software) you pass in the flag "collapse_resource_groups"

Flag Description Required/Optional
"collapse_resource_groups": true/false Set this to false if you want a unique software entry for each resource_group (or rp_name) where the software is available.
Default: true
Format as: -d '{ "software": ["software_name"], "collapse_resource": true}' 


"data": [
{
    "software_name": "tensorflow",
    "rp_name": "aces",
    "rp_resource_id": [
    "aces.tamu.access-ci.org"
    ]
},
{
    "software_name": "tensorflow",
    "rp_name": "bridges-2",
    "rp_resource_id": [
    "bridges2-gpu.psc.access-ci.org",
    "bridges2-rm.psc.access-ci.org",
    "bridges2-em.psc.access-ci.org",
    "bridges2-gpu-ai.psc.access-ci.org"
    ]
},
{
    "software_name": "tensorflow",
    "rp_name": "delta",
    "rp_resource_id": [
    "delta-cpu.ncsa.access-ci.org",
    "delta-gpu.ncsa.access-ci.org"
    ]
},
{
    "software_name": "tensorflow",
    "rp_name": "anvil",
    "rp_resource_id": [
    "anvil-ai.purdue.access-ci.org",
    "anvil.purdue.access-ci.org",
    "anvil-gpu.purdue.access-ci.org"
    ]
}
]
Optional

API Examples

Example query that will retrieve all the information in our database about 7z (remember to replace your_api_key with your personal API Key):

curl https://sds-ara-api.access-ci.org/api/v1 -X POST -H "Content-Type: application/json" -H "X-API-Key: your_api_key" -d '{"software":["7z"]}'

Example of a query that will retrieve information on Anvil:

curl https://sds-ara-api.access-ci.org/api/v1 -X POST -H "Content-Type: application/json" -H "X-API-Key: your_api_key" -d '{"rps":["anvil"]}'

Example of a query that will retrieve information on Expanse and Anvil, excluding some of the AI-generated information:

curl https://sds-ara-api.access-ci.org/api/v1 -X POST -H "Content-Type: application/json" -H "X-API-Key: your_api_key" -d '{"rps":["anvil", "expanse.sdsc.access-ci.org"], "columns":["ai_description"], "exclude":true}'

Example query for to perform a fuzzy search combining RP and software name:

curl https://sds-ara-api.access-ci.org/api/v1 -X POST -H "Content-Type: application/json" -H "X-API-Key: your_api_key" -d '{"rps":["anvil", "bridges"], "software":["blas"], "fuzz_rp":true, "fuzz_software":true}'