Python API – Moveshelf

The Python API simplifies integration with Moveshelf for Python developers. It abstracts authentication, request handling, and common tasks into an intuitive, high-level interface, allowing developers to focus on building solutions without needing to manage the complexities of API interactions. By offering built-in support for executing GraphQL queries and mutations, the Python API enables seamless data retrieval and manipulation while integrating naturally with Python's extensive ecosystem of libraries. This makes it an ideal choice for automating workflows, processing data, and creating custom scripts that interact with Moveshelf resources.

Install the Python API via PyPI: pip install moveshelf-api
You can find the documentation for the Python API here.

Basic usage example: downloading data via the Python API

Follow the steps in this section to run an existing example of querying and downloading data from the Moveshelf platform, available in the public GitHub repository.

Run the download_data_example script

Follow the instructions on GitHub, starting from the ‘API Key’ step.
Open the download_data_example Python script in Visual Studio Code, follow the instructions, add all relevant information to the script and save the file
To run the script, open a terminal and execute the following command:
python scripts/download_data_example.py

Advanced usage example: extending the Python API with a custom query

If you need queries that are not included in the default Python API, you can create a custom API wrapper that extends it with custom GraphQL queries. This section demonstrates how to create a custom API wrapper defining a new method (getProjectSubjectsCustom) to retrieve, for a given project, all subjects' name, ID, andmetadata, and all their sessions' ID, date, and metadata.

Create a custom API wrapper:
Create a new Python file, e.g., api.py, and define a subclass of MoveshelfApi (see code snippet below). This allows you to extend the existing API by adding custom GraphQL queries. For example, the built-in getProjectSubjects function only retrieves subject names and IDs. In the example below, we define getProjectSubjectsCustom, that extends the built-in getProjectSubjects function to also retrieve subject metadata and session details (ID, date, and metadata).

from moveshelf_api.api import MoveshelfApi

# Custom Moveshelf API class that extends the existing API

class MoveshelfApiCustomized(MoveshelfApi):

    def getProjectSubjectsCustom(self, project_id):
        data = self._dispatch_graphql(
            '''
            query getProjectPatients($projectId: ID!) {
                node(id: $projectId) {
                    ... on Project {
                        id,
                        name,
                        description,
                        canEdit,
                        patients {
                            id
                            name
                            metadata
                            sessions {
                                id
                                date
                                metadata
                            }
                        }
                    }
                }
            }
            ''',
            projectId = project_id
        )
        return data['node']['patients']

Use the custom API in your processing script

To use your extended API, import the custom class into your processing script, e.g., ‘download_data_example.py’. The example below shows how to call getProjectSubjectsCustom to retrieve additional metadata for all subjects and their sessions.

parentFolder = os.path.dirname(os.path.dirname(__file__))
sys.path.append(parentFolder)
from api.api import MoveshelfApiCustomized

## Setup the API
# Load config
with open(os.path.join(parentFolder, "mvshlf-config.spec.json"), "r") as configFile:
    data = json.load(configFile)

# And overwrite if available
personalConfig = os.path.join(parentFolder, "mvshlf-config.json")
if os.path.isfile(personalConfig):
    with open(personalConfig, "r") as configFile:
        data.update(json.load(configFile))

# Use custom API
api = MoveshelfApiCustomized(api_key_file=os.path.join(parentFolder, data["apiKeyFileName"]), api_url=data["apiUrl"])

# ... rest of the code to access a project on Moveshelf via API ..

# Custom query (defined in ../api/api.py) that extracts the metadata of all patients
# and the metadata of all their sessions within a given project
subjects = api.getProjectSubjectsCustom(my_project_id)

# Print the subject data
for subject in subjects:
    print(f"Subject: {subject['name']} (ID: {subject['id']})")
    print(f"Metadata: {subject['metadata']}")
    print("Sessions:")
    for session in subject['sessions']:
        print(f" - Session {session['id']} on {session['date']} with metadata: {session['metadata']}")