Web API

Note

This page contains the draft API specification and documentation for web access to the echoSMs anatomical data store. It is a work in progress. The example data available from the web API may not always be consistent with the datastore schema.

Introduction

The anatomical data store API is implemented as a RESTful web API with calls to:

1. Query dataset metadata
2. Obtain specimen information and model definitions and parameters.
3. Access the full dataset associated with a model (this includes the raw data, processing scripts, intermediate data, etc).

A testing server is available with some sample data, along with the API documentation. Example Python code that demonstrates use of the API is available here. That code also includes an example of how to download all specimen data to a local file for offline access.

Info

The structure of the data received from the API is a slightly modified version of the data that was uploaded. The main difference is that the hierarchical specimen structure has been flattened into the dataset structure - this provides a more tabular structure that is easier to work with.

API endpoints to modify the data store have not yet been created as the data store can be manually loaded given the relatively low rate of expected model uploading.

Example API calls

Some example API calls are:

• A list of all specimens
• A list of all specimens in the CLAY_HORNE dataset
• A list of all specimens with a shape type of outline
• A list of all specimens with genus of Champsocephalus
• All data from the CLAY_HORNE_B specimen and an image of that specimen
• A specimen with a shape type of voxels (and the metadata about that specimen)
• A specimen with a shape type of surface (and the metadata)

The API call to get the full raw data is not yet implemented.

Use with spreadsheets

Microsoft Excel and Google Sheets can load data directly from the datastore API. For Excel navigate to the Data tab and choose Get data->From Other Sources->From Web, enter the specimens endpoint (https://echosms-data-store-app-ogogm.ondigitalocean.app/v2/specimens) and then use the Power Query Editor to select columns before loading into Excel. For Google Sheets use one of the many API/Data Connector add-ons (e.g. API Connector).