REST API reference¶
Summary
The following document is a reference guide for all the REST APIs that InvenioRDM exposes.
Intended audience
This guide is intended for advanced users, and developers of InvenioRDM that have some experience with using REST APIs and are aware of the expected functionality a repository would be exposing.
Authentication¶
The only authentication method supported at the moment for REST API calls is by using Bearer tokens that you can generate at the "Applications" section of your user account's settings of your InvenioRDM instance. There are two ways to pass the tokens in your requests.
Authorization HTTP header (recommended)
curl -k -H "Authorization: Bearer API-TOKEN" https://127.0.0.1:5000/api/records
access_token HTTP query string parameter
curl -k https://127.0.0.1:5000/api/records?access_token=API-TOKEN
Insecure connection
The -k or --insecure option here is simply because a certificate is typically not setup locally. In production,
your curl calls shouldn't need this option because you will be using a valid certificate.
Scopes¶
Work in progress
The available scopes for generated token are subject to change when the access control mechanisms to records are finalized.
When you create your API token you can also specify scopes that control what kind of resources and actions you can access using your token.
| Scope | Description |
|---|---|
user:email |
Allows access to the user's email address |
Bear in mind, user:email is the only scope that exists by default. If you require further customization, consider customizing your authentication and delegating rights via scopes.
General information¶
Example¶
We provide an example of how to upload a record with files to an InvenioRDM instance in the following repository.
Timestamps¶
Timestamps are in UTC and formatted according to ISO 8601.
Pretty print JSON¶
If you are exploring the API via a browser, you can have the JSON formatted by
adding prettyprint=1 in the query string.
Example request
GET /api/records?prettyprint=1 HTTP/1.1