The Documents Resource

GET /documents

Get list of user's PROV documents.

Request

Query Parameters

creatorId (optional)

Returns documents created by user with this id instead of signing user's documents. Only works if signing user is an admin. For example, admin can call GET /documents?creatorId=21 to get the list of documents created by the user with id 21.

Header Parameters

authentication headers

Accept

Value should be application/json.

Response

The description property is optional.

Body

{
    "documentMetadataList": {
        "documentMetadata": [
            {
                "id": "2643",
                "version": 0,
                "name": "prov-info",
                "creator": "user123",
                "creatorId": 21,
                "createTime": "2016-08-10T16:05:21Z",
                "description": "My PROV info"
            },
            {
                "id": "2682",
                "version": 0,
                "name": "myProv",
                "creator": "user123",
                "creatorId": 21,
                "createTime": "2016-08-10T16:19:17Z"
            },
            {
                "id": "2721",
                "version": 0,
                "name": "1k-test",
                "creator": "user123",
                "creatorId": 21,
                "createTime": "2016-08-10T16:25:40Z"
            }
        ]
    }
}

GET /documents/{docId}

Get the metadata associated with a document. Only the creator or an admin can get a document's metadata.

Request

Path Parameters

docId

The documentMetadata.id of the desired document.

Header Parameters

authentication headers

Accept

Value should be application/json.

Response

The description property is optional.

Body

{

    "documentMetadata": {
        "id": "2643",
        "version": 0,
        "name": "prov-info",
        "creator": "user123",
        "creatorId": 21,
        "createTime": "2016-08-10T16:05:21Z",
        "description": "My PROV info"
    }

}

PATCH /documents/{docId}

Modify the metadata associated with a document. Only the creator or an admin may modify a document's metadata.

Request

Path Parameters

docId

The documentMetadata.id of the document.

Header Parameters

authentication headers

Accept

Value should be application/json.

If-Match (optional)

The update will fail if the server's documentMetadata.version does not match the value of this header.

Body

{
    "documentMetadata": {
        "id": "2685",
        "name": "new name for doc",
        "description": "A new description"
    }
}

Response

Body

{
    "documentMetadata": {
        "id": "2685",
        "version": 1,
        "name": "new name for doc",
        "creator": "user123",
        "creatorId": 57,
        "createTime": "2016-08-10T16:19:17Z",
        "description": "A new description"
    }
}

POST /documents/content

Upload a PROV document. Supported file types are PROV-XML and PROV-N.

Request

Header Parameters

authentication headers

filename

The name to be associated with the document. The uploaded document itself is not saved, so it generally does not make sense to include a provx or provn extension. The original format is not preserved.

Content-Type

Must be application/provenance+xml for PROV-XML or text/provenance-notation for PROV-N.

Content-MD5

The Base64 encoding of the MD5 sum of the file being uploaded. This value will also be used when constructing the signature for authentication.

Body

A PROV-XML or PROV-N file or input stream.

Response

Body

{

    "documentMetadata": {
        "id": "2643",
        "version": 0,
        "name": "prov-info",
        "creator": "user123",
        "creatorId": 21,
        "createTime": "2016-08-10T16:05:21Z"
    }

}

GET /documents/{docId}/content

Download a document. Supported dowload types are PROV-XML and PROV-N. You must be the creator or an admin to download a document.

Request

Path Parameters

docId

The documentMetadata.id of the document to be downloaded.

Header Parameters

authentication headers

Accept

The media type of the desired format. Must be application/provenance+xml for PROV-XML or text/provenance-notation for PROV-N.

Response

Body

The content of the requested document in the requested format.

DELETE /documents/{docId}

Delete a document. To delete a document you must be the creator or an admin.

Request

Path Parameters

docId

The documentMetadata.id of the document to be deleted.

Header Parameters

authentication headers

If-Match (optional)

The delete will fail if the server's documentMetadata.version does not match the value of this header.

Response

There will be a 204 No Content response upon successful deletion.

GET /documents/{docId}/types

Get list of types contained in a document. Types are returned as a typePage. A document may contain more than one page of types. See the pageToken query parameter for details. See /types for more services dealing with types.

Request

Path Parameters

docId

The documentMetadata.id of the document.

Query Parameters

pageToken (optional)

If omitted, the first page of types will be returned. If there are more types available in the document the response will contain a nextPage property. This value can be passed as pageToken to get the next page of results. The final page will have no nextPage property.

Header Parameters

authentication headers

Accept

Value should be application/json.

If-Match (optional)

If the server's value of documentMetadata.version does not match this value, the request will fail.

Response

Body

{
    "typePage": {
        "pageToken": "0",
        "nextToken": "10",
        "types": [
            {
                "id": "1048576",
                "name": "ENTITY",
                "provId": "http://www.example.org/article"
            },
            {
                "id": "1048577",
                "name": "ENTITY",
                "provId": "http://www.example.org/dataset1"
            },
            {
                "id": "1048578",
                "name": "ENTITY",
                "provId": "http://www.example.org/regionList"
            },
            {
                "id": "1048579",
                "name": "ENTITY",
                "provId": "http://www.example.org/composition1"
            },
            {
                "id": "1048580",
                "name": "ENTITY",
                "provId": "http://www.example.org/chart1"
            },
            {
                "id": "1048599",
                "name": "ENTITY",
                "provId": "dataSet2"
            },
            {
                "id": "1048600",
                "name": "ENTITY",
                "provId": "chart2"
            },
            {
                "id": "1048605",
                "name": "ENTITY",
                "provId": "http://www.example.org/instructions"
            },
            {
                "id": "1048614",
                "name": "ENTITY",
                "provId": "http://example.org/quoteInBlogEntry-20130326"
            },
            {
                "id": "1048616",
                "name": "ENTITY",
                "provId": "http://www.example.org/articleV1"
            }
        ]
    }
}

GET /documents/{docId}/relations

Get list of relations contained in a document. Relations are returned as a relationPage. A document may contain more than one page of relations. See the pageToken query parameter for details. See /relations for more services dealing with relations.

Request

Path Parameters

docId

The documentMetadata.id of the document.

Query Parameters

pageToken (optional)

If omitted, the first page of relations will be returned. If there are more relations available in the document the response will contain a nextPage property. This value can be passed as pageToken to get the next page of results. The final page will have no nextPage property.

Header Parameters

authentication headers

Accept

Value should be application/json.

If-Match (optional)

If the server's value of documentMetadata.version does not match this value, the request will fail.

Response

Body

{
    "relationPage": {
        "pageToken": "0",
        "nextToken": "10",
        "relations": [
            {
                "id": "1048593",
                "name": "ATTRIBUTION",
                "subject": {
                    "name": "entity",
                    "provId": "http://www.example.org/chart1"
                },
                "object": {
                    "name": "agent",
                    "provId": "http://www.example.org/derek"
                }
            },
            {
                "id": "1048611",
                "name": "START",
                "subject": {
                    "name": "activity",
                    "provId": "http://www.example.org/correct1"
                },
                "object": {
                    "name": "trigger"
                },
                "secondaryObject": {
                    "name": "starter"
                }
            },
            {
                "id": "1048617",
                "name": "SPECIALIZATION",
                "subject": {
                    "name": "specificEntity",
                    "provId": "http://www.example.org/articleV1"
                },
                "object": {
                    "name": "generalEntity",
                    "provId": "http://www.example.org/article"
                }
            },
            {
                "id": "1048619",
                "name": "SPECIALIZATION",
                "subject": {
                    "name": "specificEntity",
                    "provId": "http://www.example.org/articleV2"
                },
                "object": {
                    "name": "generalEntity",
                    "provId": "http://www.example.org/article"
                }
            },
            {
                "id": "1048591",
                "name": "ASSOCIATION",
                "subject": {
                    "name": "activity",
                    "provId": "http://www.example.org/compose1"
                },
                "object": {
                    "name": "agent",
                    "provId": "http://www.example.org/derek"
                },
                "secondaryObject": {
                    "name": "plan"
                }
            },
            {
                "id": "1048592",
                "name": "ASSOCIATION",
                "subject": {
                    "name": "activity",
                    "provId": "http://www.example.org/illustrate1"
                },
                "object": {
                    "name": "agent",
                    "provId": "http://www.example.org/derek"
                },
                "secondaryObject": {
                    "name": "plan"
                }
            },
            {
                "id": "1048597",
                "name": "ASSOCIATION",
                "subject": {
                    "name": "activity",
                    "provId": "http://www.example.org/compose1"
                },
                "object": {
                    "name": "agent",
                    "provId": "http://www.example.org/derek"
                },
                "secondaryObject": {
                    "name": "plan"
                }
            },
            {
                "id": "1048607",
                "name": "ASSOCIATION",
                "subject": {
                    "name": "activity",
                    "provId": "http://www.example.org/correct1"
                },
                "object": {
                    "name": "agent",
                    "provId": "http://www.example.org/edith"
                },
                "secondaryObject": {
                    "name": "plan",
                    "provId": "http://www.example.org/instructions"
                }
            },
            {
                "id": "1048586",
                "name": "GENERATION",
                "subject": {
                    "name": "entity",
                    "provId": "http://www.example.org/composition1"
                },
                "object": {
                    "name": "activity",
                    "provId": "http://www.example.org/compose1"
                }
            },
            {
                "id": "1048588",
                "name": "GENERATION",
                "subject": {
                    "name": "entity",
                    "provId": "http://www.example.org/chart1"
                },
                "object": {
                    "name": "activity",
                    "provId": "http://www.example.org/illustrate1"
                }
            }
        ]
    }
}