What is Trovi?

Trovi is a public service and open API that provides storing, referencing, and reproducing research artifacts. Applications can integrate with the Trovi API to provide the following capabilities to their users:

• Artifact upload and storage: users can upload files representing their experiment in whatever form appropriate (e.g., documentation, Jupyter notebooks, setup scripts, data sets, example output). Currently Trovi integrates with several storage backends, notably 's object store and , though future integrations are possible.

• Artifact lifecycle management: artifact owners can publish new versions of their artifact and apply useful metadata (e.g., tags, short descriptions, author list).

• Sharing artifacts, publicly or during embargo/development: generate private links that allow others to access the artifact's contents (e.g., for evaluation), or publish particular versions of the artifact for open access, including DOI assignment.

• Instantiate artifacts within a variety of environments: users can "re-play" an artifact, opening it on their local machine or within an open testbed environment. Testbeds can leverage existing general-purpose integrations (e.g., ) or build their own.

• Build upon a catalog of relevant research artifacts and examples: users can "fork" existing artifacts and create their own revision, or use existing work as a template or example for future research.

What is an Artifact?

Currently, Trovi makes only a few assumptions about an Artifact:

• It contains some tarball of contents representing the portable portion of the artifact. This means source code, instructions, notebooks, and examples.

• External requirements, such as disk images hosted on a target infrastructure, datasets, etc., can be specified with link references (pointers.) These links are opaque from Trovi's point of view, enabling integrations specific to third-parties.

Who can use Trovi?

Trovi's allows federation with select partners, enabling any user of a participating entity in the federation to utilize the API or any of its integrations. If you're interested in becoming part of the Trovi federation, please .

Trovi API Reference

Dive a little deeper and start exploring our API reference to get an idea of everything that's possible with the API:

Want to contribute, or just peek at the source code?

Take a look at our GitHub repository! There, you can read the source code, or open an issue, discussion, or pull request.

Required token scope

• artifacts:read

• artifacts:write

Required token scope

• artifacts:read

Required token scope

• artifacts:read

• artifacts:write

Required token scope (origin)

• artifacts:read

Required token scope (access_token)

• artifacts:write_metrics

Version metrics describe the history of user interaction with Artifact Versions. There is presently 1 type of action: access_count. This describes the number of times an experiment has been launched by a different user. Client applications are responsible for properly notifying Trovi when these events happen.

Artifacts have ordered versions to distinguish between changes over time. The version endpoints are how you can create a new version, or delete an existing one.

Required token scope

• artifacts:read

• artifacts:write

Required token scope

• artifacts:read

Functions the same as , but requires the Artifact UUID and version slug for a faster lookup.

Required token scope

• artifacts:read

Required token scope

• artifacts:read

Sometimes, users may wish to move their stored contents to a different platform (backend). We offer endpoints to accomplish this. One way we use this endpoint is to allow users to upload contents to our object storage, and then later allow users to request a DOI. When this happens, we migrate their content from the object storage backend to Zenodo.

Artifact versions must have contents (usually code or notebooks) attached to them. The Contents endpoints are used for uploading contents to supported data stores, and retrieving metadata about those contents, including download links.

Required token scope

• artifacts:write

Required token scope

• artifacts:read

Required token scope

• artifacts:write

Required token scope

• artifacts:read

Once a Trovi Token is exchanged, it is used to authenticate to any Trovi endpoint by attaching it to the URL via the access_token parameter.

Users must obtain an authentication token from one of the supported Trovi identity providers, and then submit that subject token to the TokenGrant endpoint in order to obtain a Trovi token. All Trovi tokens adhere to the following properties:

• Expire 5 minutes after they are issued

• Are in the JWT format (JWS string)

Required token scope

• None, but the user must be authenticated to Trovi

Artifacts may have individual roles assigned to users which permit access control for those users. There are two types of role:

• Administrator

• Collaborator

Administrator

Administrators have full control over the artifact, including assigning and unassigning roles. Administrators may upload, download, delete, and change content as they see fit.

Collaborator

Collaborators have permission to edit artifact metadata, upload new versions, and share private artifacts.

These endpoints describe metadata about the Trovi API itself, as opposed to individual Artifacts.

A URN (Uniform Resource Name) is a standard format for identifying online resources. They are used throughout Trovi to represent various forms of data. A URN is a string in the format of urn:<nid>:<nss>. nid stands for "namespace identifier," and nss stands for "namespace-specific string." The NID is a single word which represents the entity which created the URN. NIDs are officially registered with IANA, but in theory, they can be anything.

Trovi has an unofficial NID of trovi. Anything not belonging to an official namespace will use the trovi NID. So, for example, a Chameleon Cloud user URN will be formatted urn:trovi:user:chameleon:<username>, because Chameleon Cloud does not have an official NID.

The only official NIDs we use are ietf, which are used in requests, and globus, which may appear in linked resources in .

Required token scope

• trovi:admin

Required token scope

• artifacts:write