Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Practical Open Reproducibility
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 Chameleon's object store and Zenodo, 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., JupyterLab) 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.
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.
Trovi's authentication model 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 contact us.
Dive a little deeper and start exploring our API reference to get an idea of everything that's possible with the API:
Take a look at our GitHub repository! There, you can read the source code, or open an issue, discussion, or pull request.
View, Modify, Create, and Delete Artifact metadata
A shortcut for retrieving contents.
Functions the same as RetrieveContents, but requires the Artifact UUID and version slug for a faster lookup.
artifacts:read
Update metadata of an existing Artifact
UpdateArtifact requests use the JSON Patch syntax. All operations except test
are supported.
Both PATCH
and PUT
requests are supported, but PUT
requests require the partial
URL argument to be set.
artifacts:read
artifacts:write
Create and Delete artifact versions
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.
Trovi's permission model
Artifacts may have individual roles assigned to users which permit access control for those users. There are two types of role:
Administrator
Collaborator
Administrators have full control over the artifact, including assigning and unassigning roles. Administrators may upload, download, delete, and change content as they see fit.
Artifact owners are automatically assigned the Administrator role. This role cannot be unassigned from owners. In order to accomplish this, the owner must first be changed to someone else via UpdateArtifact.
Collaborators have permission to edit artifact metadata, upload new versions, and share private artifacts.
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.
Migrate the stored content of an Artifact version to a different storage platform
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.
Queue an artifact version's contents to be transferred to a different storage backend.
Performing a migration submits a migration task onto a queue, and receiving a successful response only means that your migration has been submitted, not that it is finished. To check on the status of your migration, use GetArtifactVersionMigrationStatus
Only one migration can be in progress at a time.
artifacts:write
Submit a subject token and receive a Trovi authentication token
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)
Token requests adhere to the following properties:
The only supported grant type is "token_exchange"
Subject tokens must be in the JWT format (JWS string)
The following scopes are available for all Trovi tokens. Currently, any requested scopes will be granted to any user. This is subject to change.
artifacts:read
- Read all artifacts which are accessible to the user
artifacts:write
- Edit all artifacts for which the user is an owner or author, and create new artifacts
artifacts:write_metrics
- Update artifact access metrics
List roles available on an artifact
Roles are also visible on the models returned by GetArtifact and ListArtifacts.
artifacts:read
Upload content and view its metadata
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.
Retrieve content metadata, including download links
If you have access to the Artifact UUID and the version slug at the time of the API call, consider using RetrieveArtifactVersionContents.
artifacts:read
A quick note on URNs
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 TokenGrant requests, and globus
, which may appear in linked resources in Artifact Versions.
Exchange subject tokens from a federated identity provider for a Trovi authentication token
Currently, the only federated identity provider supported is Chameleon Keycloak. To have your application added to the list of approved identity providers, please fill out the Google Form attached to this page.
Supported identity providers must speak OpenID Connect.
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.
These endpoints describe metadata about the Trovi API itself, as opposed to individual Artifacts.
Create a new Trovi tag which can be applied to Artifacts.
List all Artifacts visible to a user
This endpoint does not require authentication
Metrics can only be incremented by registered service applications. To register your application for this privilege, please get in touch with the Trovi developers.
The metrics endpoint is unique, in that callers must authenticate as the client application itself, and pass the user's token via the origin
URL parameter. The reason for this is because we don't want users to be able to freely increment metrics as they please, so we only allow registered clients to do so, but we still require the user token in order to ensure that the user has permission to interact with the Artifact in the way that would increase the relevant metric.
artifacts:read
artifacts:write_metrics
List all the tags available in Trovi
This endpoint does not require authentication