RSpace API Introduction

RSpace supports a RESTful API. RSpace users can programmatically search, review and retrieve data in RSpace which in turn enables you to integrate RSpace into existing workflows with ease.

The RSpace API enables programmatic search and retrieval methods for your documents. There are multiple GET methods for files and documents allowing for in-depth searches, the retrieval of complete documents and their metadata and the processing of data contained in forms.  There are also  POST methods to create new content and upload files.

Where to find information on the API?

• The API is being continually expanded; please see the changelog for details.
• The latest public API documentation is always available on our Community site.
• An API tutorial, introducing the RSpace API, is available on our GitHub as well.
• The data model is a simplified version of RSpace's internal model.

Tools and SDKs

• We are developing rich language bindings and example code on our Github page for Python, Java and others.
• An open-source RSpace Command Line Interface (CLI) provides a convenient and compact way to access the API.

Obtaining your API Key

RSpace uses API Keys for the authorisation and authentication.

You can always regenerate or revoke your key. You can generate your API key in RSpace as follows:

1. Login to RSpace and go to the ‘My RSpace’ page

1. Click on the ‘My Profile’ tile

1. Under the ‘Manage API key’ header, click on the ‘Generate key’ button

1. A pop up box will appear asking you to enter your RSpace login password

1. Type your password and click ‘OK’

1. If you look under the "Manage API key" header, you will see your API key has been generated. You can now also see the option to revoke the key (to delete it).

1. You need to save your API key in a safe place outside RSpace. Infact once you refresh the page (and for now on) you will see the sentence "The current key was generated today" set instead of the actual key

API Key Authentication and Swagger Documentation

Swagger documentation for the RSpace API is available at http://<rspace_instance>/public/apiDocs (https://community.researchspace.com/public/apiDocs for community users).

This documentation not only shows examples of requests you may with to make, but you can run real requests on your version of RSpace, following API key authentication.

To authenticate your key and use Swagger to explore the API do the following:

1. Go to the Swagger documentation for your instance of RSpace. This may be accessed by clicking on the ‘See API Documentation’ link in your RSpace profile (My RSpace > My Profile > under "Manage API key"), or alternatively at http://<rspace_instance>/public/apiDocs (for Community RSpace this is at https://community.researchspace.com/public/apiDocs)
2. Click the ‘Authorize’ button on the Swagger page that opens, right below the introduction.

1. Enter your current API key into the pop-up box provided and click ‘Authorize’

1. You are now able to run requests via the Swagger interface.

OAuth for RSpace

A tutorial for the initial implementation of OAuth with RSpace is available as part of our API Tutorial.

API Security

We strongly urge you to keep your API key private. If using your API key on a shared computer, ensure it is not stored in a world-readable file.

You may regenerate your API key at any time by clicking on the ‘Regenerate Key’ button. When your new key is generated, the old key will become invalidated.

To block API access altogether you can simply click on the ‘Revoke Key’ button, to delete the API key.

Both of these options can be found under My RSpace > My Profile, in the "Manage API key" section:

Simple example using Apple Mac terminal to upload a file to the gallery

See youtube video here.

You can try something similar using by downloading the ZIP file below and following the instructions in the readme file.

Download .ZIP file

This workflow can be useful for tasks such as collecting files output by instruments and sending them automatically to RSpace.