SDKs overview

Open Science Framework (OSF) provides programmatic access to its platform through a RESTful API. This API allows developers and researchers to interact with OSF data and services, including managing projects, uploading and downloading files, handling registrations, and accessing user information. The API adheres to the JSON:API specification for RESTful APIs, which standardizes how clients request and modify resources and how servers respond to these requests. This approach aims to reduce the number of requests and the amount of data transmitted between clients and servers, improving efficiency and consistency for developers working with OSF resources.

The primary method for integration is directly through the HTTP API. However, to facilitate development and reduce boilerplate code, OSF offers official SDKs for popular programming languages. These libraries abstract the underlying HTTP requests and JSON:API parsing, providing language-specific objects and methods for interacting with OSF. For use cases requiring custom integrations or languages not supported by official SDKs, direct API calls remain an option. Authentication for the OSF API typically involves OAuth2 for applications or Personal Access Tokens (PATs) for scripting and command-line interactions, enabling secure access to user data and resources OSF API documentation.

Official SDKs by language

Open Science Framework maintains official SDKs designed to streamline development in specific programming environments. These SDKs simplify common API interactions, such as authentication, request formatting, and response parsing, allowing developers to focus on integrating OSF functionality into their applications rather than handling the intricacies of the API protocol.

The following table lists the official SDKs supported by OSF:

Language Package Name Install Command Example Maturity Key Features
Python osfclient pip install osfclient Stable File management, project interaction, command-line interface
R osfr install.packages("osfr") Stable Project/component management, file operations, user data access

The osfclient Python library provides both a command-line interface (CLI) and a Python API for interacting with OSF. It is particularly useful for scripting tasks such as uploading and downloading files, managing project structures, and automating data synchronization with OSF storage. The R package osfr is tailored for researchers and developers working within the R ecosystem, offering functions to create and manage OSF projects, upload research data, retrieve files, and integrate with R-based data analysis workflows OSF developer guides.

Installation

Installing the official Open Science Framework SDKs is typically straightforward, using the standard package managers for Python and R. The following instructions detail the common installation methods:

Python (osfclient)

The osfclient package can be installed using pip, the Python package installer. It is recommended to install it within a virtual environment to avoid conflicts with system-wide Python packages:

# Create a virtual environment (optional but recommended)
mkdir osf_project
cd osf_project
python -m venv venv
source venv/bin/activate  # On Windows, use `venv\Scripts\activate`

# Install osfclient
pip install osfclient

After installation, you can verify it by running osf --version in your terminal. For authenticating with the OSF API, osfclient can be configured with a Personal Access Token (PAT). A PAT can be generated from your OSF profile settings OSF Personal Access Token documentation. Once you have a PAT, you can set it as an environment variable or configure it via the client:

export OSF_TOKEN="your_personal_access_token_here"

Alternatively, osfclient can prompt you for your credentials on first use, which it will then cache securely.

R (osfr)

The osfr package is available on CRAN (Comprehensive R Archive Network) and can be installed using R's built-in install.packages() function:

# Install osfr from CRAN
install.packages("osfr")

# Or, for the development version from GitHub (requires devtools)
# install.packages("devtools")
# devtools::install_github("centerforopenscience/osfr")

Once installed, load the library into your R session:

library(osfr)

Authentication with osfr also typically involves an OSF Personal Access Token. You can set this token as an environment variable (e.g., OSF_PAT) or pass it directly to authentication functions within the package. For example, osf_auth(token = "your_personal_access_token") can be used to authenticate interactively or programmatically within an R script OSF API usage instructions.

Quickstart example

This quickstart demonstrates basic operations using the osfclient Python SDK, such as listing projects and downloading a file from an OSF project. This assumes you have already installed osfclient and configured your Personal Access Token.

Python (osfclient) - List Projects and Download File

First, ensure your OSF_TOKEN environment variable is set with your Personal Access Token. If not, follow the installation steps to set it.

import os
from osfclient.api import OSF

# Initialize the OSF client (it will pick up OSF_TOKEN from environment)
osf = OSF()

# List your OSF projects
print("Your OSF Projects:")
for project in osf.projects:
    print(f"- {project.title} (ID: {project.id})")

# Example: Find a specific project by title or ID
project_title = "My Research Project"
target_project = None
for project in osf.projects:
    if project.title == project_title:
        target_project = project
        break

if target_project:
    print(f"\nWorking with project: {target_project.title}")

    # List files within the project's primary storage (OSF Storage)
    print("\nFiles in OSF Storage:")
    osf_storage = target_project.storage('osfstorage')
    for file_obj in osf_storage.files:
        print(f"- {file_obj.name} (Path: {file_obj.path})")

    # Example: Download a specific file
    file_to_download_name = "data.csv"
    for file_obj in osf_storage.files:
        if file_obj.name == file_to_download_name:
            print(f"\nDownloading '{file_obj.name}'...")
            # Specify the local path where the file should be saved
            local_download_path = os.path.join(os.getcwd(), file_obj.name)
            file_obj.download(local_download_path)
            print(f"'{file_obj.name}' downloaded to {local_download_path}")
            break
    else:
        print(f"File '{file_to_download_name}' not found in project '{project_title}'.")
else:
    print(f"Project '{project_title}' not found.")

This script first initializes the OSF client, then iterates through all projects associated with the authenticated user, printing their titles and IDs. It then attempts to locate a project by a predefined title. If found, it lists the files stored within the project's OSF Storage component and demonstrates how to download a specific file to the current working directory. This provides a foundational understanding for automating data retrieval and project management on OSF using Python.

Community libraries

While Open Science Framework provides official SDKs, the open-source nature of the platform and its API encourages the development of community-contributed libraries and tools. These libraries can extend functionality, offer support for additional programming languages, or provide specialized features not covered by the official SDKs. Community libraries often emerge from specific research needs or preferences for certain development environments.

Developers exploring OSF integrations in languages other than Python or R may find community-driven efforts useful. These could include:

  • JavaScript/Node.js clients: For web applications or server-side Node.js environments that need to interact with OSF data. While not officially maintained by OSF, various npm packages might offer wrappers around the OSF API.
  • Command-line tools: Beyond osfclient, other scripts or utilities might exist that leverage the OSF API for specific automation tasks or data synchronization.
  • Specialized data connectors: Libraries that facilitate connecting OSF data directly to analytical platforms, databases, or visualization tools.

When considering community libraries, it is important to evaluate their maintenance status, documentation, and community support. Resources like GitHub and relevant developer forums for open science projects are common places to discover and assess such contributions. Developers should verify compatibility with the latest OSF API versions, as API changes can impact the functionality of unofficial clients. The OSF developer documentation itself serves as the authoritative reference for the API specification, which any third-party library must adhere to OSF API specification.