RSpace API Tutorial

Introduction

This project provides an introduction to using the RSpace API.

Who is this tutorial for?

This tutorial is intended for software developers, or scientists with programming skills, to learn how to use the RSpace API to interact programmatically with the RSpace Electronic Lab Notebook. All the examples can be run using a personal API token.

How does this tutorial fit in with other RSpace API documentation?

• The RSpace help documentation describes how to get your API token from the RSpace UI.
• The API technical reference describes low-level technical details of the API endpoints and API contracts.
• Example code projects provide language-specific API client example code.

What version of RSpace is required for this tutorial?

RSpace 1.63 or newer is needed to follow all the steps.

How do I develop client Apps for RSpace?

This tutorial covers use of personal access tokens. If you are a developer looking to incorporate OAuth authentication for a client app then please read Using OAuth.

For development purposes we have a Dockerised version of RSpace which lets you test your client application against a real instance of RSpace. Please ask us, or view our Docker Documentation

Can I contribute to this documentation?

Yes. Please see CONTRIBUTING.md, which points to the RSpace open source community contribution guidelines and code of conduct. Contributors are acknowledged in CONTRIBUTORS.md.

Use-cases for the API

• Uploading files from instruments or your device into RSpace automatically.
• Creating RSpace documents and linking to files.
• Adding or editing content in an RSpace document.
• Searching and retrieving files and documents.
• Creating folders and notebooks for organising content.
• Creating and publishing forms.
• Sharing RSpace documents.
• Importing MSWord or OpenOffice documents into RSpace.
• Scheduled exports of your work.
• Creation of user accounts and groups (admins only).

Getting started

• Follow the instructions in the RSpace help documentation to get set up with an API key for your account.
• This tutorial will use curl commands to make API calls rather than assume a particular programming language.

Code examples are shown in the following syntax:

curl -v -H "accept: application/json" -H "apiKey:$API_KEY" "$RSPACE_URL/api/v1/files"

• The -v option to curl shows verbose information about the request to help you debug any problems.
• You generally need to supply the content type to be accepted, and your API key, as request headers. Replace $API_KEY with your own key. You can export this as an environment variable. This is good practice, as it avoids putting secret information on the command line, e.g. in a Bash shell:

export API_KEY=mysecretkey

Please note that Bash will save this into the .bash_history file in the home directory. It is possible to disable the logging of export statements.

• Replace $RSPACE_URL with the base URL of your RSpace installation. E.g. if you're using RSpace Community, this would be https://community.researchspace.com. You can export this as an environment variable as well, e.g. in a Bash shell:

export RSPACE_URL=https://community.researchspace.com

• Any other text in <ANGLE_BRACKETS> is a placeholder for a value specific to your account, e.g. a resource identifier.
• You can check your setup by making a simple call to the /status endpoint:

curl -H "apiKey:$API_KEY" "$RSPACE_URL/api/v1/status"

All code snippets are provided as working examples in the examples folder in this project. Where a command references an example file (for instance -d "@examples/creatingDocument/basicDocument-named-withContent.json"), run it from the root of this repository so the relative path resolves.

Guides

Creating and editing content:

• Files - uploading, downloading and replacing files.
• Documents - creating and editing documents, linking to files and other records, deleting content.
• Folders and notebooks - creating folders and notebooks, and navigating the folder tree.
• Forms - listing, searching, creating, publishing and deleting forms.

Working with your data:

• Sharing - sharing documents and notebooks with groups and users.
• Exporting - programmatic HTML/XML exports as asynchronous jobs.
• Importing - importing from MSWord, Evernote, and linking to Dropbox, OneDrive or Box.
• Polling for events - detecting changes via the /activity endpoint.

Authentication and administration:

• OAuth - OAuth authentication for client apps.
• Accounts - creating user accounts and groups (SYSADMIN only).

Worked examples:

• Cookbook - end-to-end recipes for specific tasks.