Documentation › API

Introduction

ProvStore's API provides a RESTful web service for storage and access of provenance documents in various formats of the W3C's PROV Data Model. Using the API, any client can manipulate documents contained in the store and explore and retrieve information from them.

This document provides details and examples of the available endpoints and resources at a low level. Existing libraries can be used instead to provide higher level access to the resources available on ProvStore.

Resources

The API currently has one resource, documents, which is documented below.

Documents

The following actions are available on the documents resource:

Action Description
GET /store/api/v0/documents/ Retrieve a list of documents visible to the authenticated user or public.
GET /store/api/v0/documents/:id/ Retrieve information about the document with the given ID.
GET /store/api/v0/documents/:id(/flattened)(/view/:view).:format Retrieve the raw body of the document with the given ID in the requested format.
POST /store/api/v0/documents/
authentication required		 Save a new document.
GET /store/api/v0/documents/:id/bundles/ List bundles of the document with the given ID.
POST /store/api/v0/documents/:id/bundles/
authentication required		 Add a bundle to the document with the given ID.
DELETE /store/api/v0/documents/:id/
authentication required		 Delete the document with the ID provided.
GET /store/api/v0/documents/:doc_id/bundles/:bundle_id(.:format)
authentication required		 View the bundle contained in the speicified document with the specified ID.

Responses

Method
Response Code
Response Description
GET 200 OK The resource was successfully retrieved.
POST 201 Created The resource was successfully created. The information held in the new resource will be provided in the response body.
POST 202 Accepted The sub-resource was successfully added to the target resource.
DELETE 204 No Content The resource was successfully deleted.
POST 400 Bad Request A problem occurred while parsing the document (wrong syntax) or adding the bundle (bundle contains a bundle or bundle ID is not unique to the document.)
Any 401 Unauthorized There is a problem with the Authentication header provided.
Any 403 Forbidden You do not have the permissions to perform the requested operation on the resource.
Any 404 Not Found The resource/url you have requested does not exist.
GET 410 Gone The resource requested is of invalid prov syntax and can no longer be served.
GET 422 Unprocessable Entity Due to semantic errors, the resource could not be returned in the desired format.
Any 500 Internal Server Error Something went wrong on the server. We will have been notified. If the problem continues contact us.

Authentication

The API supports authentication by using an API key. The API can also be accessed anonymously if you do not wish to authenticate. In this case only public documents will be visible and documents may not be added/modified.

API Key

To authenticate via API Key you must first have generated an API key (in your Developer Area) which will be sent along with your username in order to authenticate. To use this key you must send an HTTP Authorization header along with your requests with a value of the format ApiKey <username>:<apikey>.

So for example if your username is 'foo' and your API key is 'b4702794b52445bab04a51ead73d5adbc554c970' you would send a HTTP Authorization header with the value: 

ApiKey foo:b4702794b52445bab04a51ead73d5adbc554c970

Libraries

Python

provstore-api

This package provides an API client for connecting with the store. View the full documentation

Install
pip install provstore-api
Usage
from provstore.api import Api

import provstore.tests.examples as examples # for this example

api = Api(username="me", api_key="XYZ")

# Store a new document
stored_document = api.document.create(prov_document, name="my document")
# Add a bundle to our document
stored_document.bundles['ex:bundle'] = prov_bundle

# Get a document with ID 148 from ProvStore:
stored_document = api.document.get(148)
# Get the document's provenance
stored_document.prov

# Delete the document with ID 148 from the store:
api.document.get(148).delete()

# Get document with this ID's bundles
for bundle in api.document.get(148).bundles:
    # print the bundle's identifier
    print bundle.identifier
    # the bundle's provenance is at:
    bundle.prov

jQuery

Using the ProvStore jQuery API plugin calls to the API can be made as follows:

Initialize API Object

var api = new $.provStoreApi({username: <username>, key: <api key>});

List document

api.getDocuments(
  <offset (integer)>,
  <limit (integer)>,
  function(data){
    /* success callback with Document List response object as param */
  },
  function(error){/* error callback */}
);

Read document

api.getDocument(
  <document ID (integer)>,
  function(data){
    /* success callback with document metadata object as param */
  },
  function(error){/* error callback */}
);

Document body

api.getDocumentBody(
  <document ID (integer)>,
  <document format (string)>, /* one of the supported formats */
  function(data){
    /* success callback with document metadata object as param */
  },
  function(error){/* error callback */}
);

Submit document

api.submitDocument(
  <document name (string)>,
  <document (PROV-JSON)>,
  <make document public (boolean)>,
  function(id){/* success callback with new document id as only parameter */},
  function(error){/* error callback */}
);

Add bundle

api.addBundle(
  <target document ID (integer)>,
  <new bundle identifier (string)>,
  <bundle (PROV-JSON)>,
  function(id){/* success callback with new document id as only parameter */},
  function(error){/* error callback */}
);

Delete a document

api.getDocument(
  <document ID (integer)>,
  function(){
    /* success callback with document metadata object as param */
  },
  function(error){/* error callback */}
);