API function overview

The Research Object API allows:

• Storing and retrieving research objects.
• Storing and retrieving resources aggregated within the research fobjects.
• Annotating the aggregated resources, including the research object itself.

RO API allows creating research objects and retrieving them in a number of formats – as RDF metadata, a ZIP archive or an HTML page. Resources can be aggregated and de-aggregated by means of proxies, which simplifies handling resources that are stored outside of the service's domain. Resources can be annotated using RDF graphs.

The RO API is based heavily on the Research Object model, version 0.1 at the moment of writing. It therefore uses the Open Annotation and the Object Reuse and Exchange models. The mechanism of using proxies and annotations as gateways for aggregated resources and annotation bodies has been based on the AtomPub specification.

API usage

Authorization

Authorization and access control policy is out of scope of this document but for simplicity, the use of OAuth 2.0 with the Bearer authorization schema will be assumed.

Get a list of Research Objects

The response format may be an RDF file or a list of URIs.

Create a new Research Object

The Research Object id can be any string. If this id is already in use, 409 Conflict will be returned.

Create a new or upload an existing RO as a zip file.

It's possible to create a completely new RO from a set of different files and folders collected in a one zip file. RO service aggregates all sent resources including folders and maintains their structure. The operation is performed in the background. User receives link to the operation status object as a server response. Status object contains information about the process status, the final uri of processed RO, possible error messages if an error occured. Status object knows how many resources were submitted and how many of them were already processed by server.

Get a copy job status (running).

Get a job status (finished).

It's possible to upload to a server an existing RO. Once server receives a zip with an existing RO, server unpacks and processes the given artifact in a background process  in a few simple steps:

1. Look for the .ro/manifest.rdf. If not found, 400 Bad Request is returned.
2. Create the RO.
3. Scan for each resource aggregated in the RO and add it to the RO.
4. If there is anything else in the zip which was not aggregated, log it but don't return error.

User receives link to the operation status object as a server response. Status object contains information about process status, the final uri of processed RO and possible error messages if an error occured. Status object knows how many resources were submitted and how many of them were already processed by server.

Get a job status (running).

Get a copy job status (finished).

Get a Research Object

What do you get when you ask for an RO? This implementation is related to the page ??RO dereferencing:

• If "text/html" is requested, the response is a 303 redirection to an HTML page representing the RO.
• If any RDF type is requested, the response is a 303 redirection to the manifest.
• If "application/zip", "multipart/related" or anything else (or nothing in particular) is requested, the response is a 303 redirection to a URI /zippedROs/:roid/. This is a specific resource only for downloading ROs as ZIP files. Requests to this resource will return a ZIP file regardless of the Accept header, which in case of web browsers is out of control of the user.

Links to all 3 formats available are included as link headers or HTML links described in the ?RO dereferencing.

This example assumes retrieving the RO metadata, i.e. the manifest.

This example assumes retrieving a zip file.

Delete a Research Object

Aggregate a resource

Each resource aggregated in the research object has an associated proxy. Proxies are references to the resource in the context of the research object and in the case of external resources, their representations in the RO API. The structure of a proxy is described by ORE.

The API design here uses similar patterns to AtomPub, with an RO being analogous to an Atom feed, a proxy for an Atom item,
and resource content for an Atom media resource. The Slug: header field is defined by AtomPub (http://tools.ietf.org/html/rfc5023).

Aggregating resources involves 2 steps, though in most cases one of them can be omitted:

1. Creating a proxy for a resource.
2. Uploading a resource.

The first step is recognized by making a request with MIME type application/vnd.wf4ever.proxy and using a resource URI not pointed to by an existing proxy. When a proxy is created, the proxy target is automatically aggregated in the research object.

The resource URI is indicated either using the Slug: header if a new internal resource is being aggregated (in which it is a relative URI reference), or in the request body otherwise. If the resource URI is not indicated in the Slug: header nor in the request body, the server should generate any URI it sees fit, i.e. using a random UUID. The server will return 409 Conflict if the resulting URI has already been aggregated in this research object. Client applications should not, however, make assumptions about the URI of the resulting resource but should, instead, use the ore:proxyFor link value returned by the service. 

Resources are aggregated in the following ways:

1. External resources: only create a proxy, pointing to the external resource.
2. Internal resources: only upload a resource. The service will create the proxy automatically and will return the URI of the proxy rather than the URI of the resource itself.
3. Internal resources, the long way: create a proxy and then upload the resource. This is the only method to add a proxy as an aggregated resource (a rare case).

The example below demonstrates aggregating an external resource. The URI of the external resource is given in the supplied proxy description. The content type application/vnd.wf4ever.proxy signals to the RO service that a new proxy is being created.

A application/vnd.wf4ever.proxy entity is an RDF/XML expression that describes just one ore:Proxy resource. Other information present in the RDF is ignored. Behaviour is undefined if there is not exactly one ore:Proxy resource described, and a service MAY reject such a request as ill-formed. (Future proposals may accept any format of RDF, and use a separate mechanism to signal that it is intended to be interpreted as a proxy description.)

The example below demonstrates adding a proxy for an internal resource, and then putting the new resource content at the server-indicated URI. The RO-internal name for the new resource is indicated using a Slug: header (following AtomPub). The supplied entity body is a Proxy description from which the proxyFor property is omitted.

The example below demonstrates the short-cut mechanism aggregating an internal resource by simply posting its content to the RO. The Slug: header is used to indicate the desired path within the RO. The server responds with the proxy description.

Update an aggregated resource

The example below demonstrates updating an internal resource. Updating external resources is out of control of the service.

Clients may use the proxy URI or, for internal resources, the resource URI.

Trying to create new content in this way or trying to update the manifest will result in 403 Forbidden.

When a resource that is RO metadata is modified, different formats can be used by means of content negotiation. For updating such resources, the clients may use either resource URIs or the format-specific URIs. Responses for PUT:

Get an aggregated resource

The default response when dereferencing the resource URI is the resource content. Resource metadata can be found in the manifest.

When dereferencing the aggregated resource proxy, the client is redirected to the resource that the proxy is for.

When retrieving resources that are RDF RO metadata, content negotiation is allowed.

• Specific RDF format can be asked using content negotiation, i.e. adding an "Accept: text/turtle" header to the request.
• If the URI has no extension or has an extension that does not match the requested format, the server will return 302 Found redirecting the client to the format-specific resource. See below.
• The format-specific resource can be used by clients to access the resource directly in a specific format without content negotiation. Note the "original" query param that identifies the format-specific version of another resource.

The table below demonstrates the expected responses for GET requests to named graphs.

Remove an aggregated resource

Removing has a slightly different meaning for internal and external resources:

• For internal resources, it means de-aggregating the resource, deleting its proxy from the manifest and deleting the resource itself.
• For external resources, it means de-aggregating the resource and deleting its proxy from the manifest.

Clients may use the proxy URI or, for internal resources, the resource URI.

For resources that have different RDF formats (i.e. RO metadata), the clients may use either resource URIs or the format-specific URIs.

Trying to remove resources that are under control of the RO service (such as aggregation resource maps) will result in 403 Forbidden.

The example below demonstrated de-aggregating an external resource.

The example below demonstrated de-aggregating an internal resource. If the internal resource has no content (i.e. only a proxy was created), there will be no redirection and the proxy will be deleted.

Annotate a resource

In order to annotate a resource, an annotation has to be created in the manifest, pointing to a set of annotated resources and an annotation body. The annotated resources must be resources already aggregated by the research object. The annotation body may an internal or external resource. In the first case, it will also have a proxy as all internal resources aggregated by the research object. The annotation body does not have to exist when annotating a resource.

Annotating resources involves 2 steps, though in some cases one of them can be omitted:

1. Creating an annotation for a resource or resources.
2. Aggregating an annotation body.

The first step is recognized by making a request with MIME type application/vnd.wf4ever.annotation. The second step is recognized by aggregating a resource that is either referenced in an existing annotation or has a Link header ao:annotatesResource.

Resources are annotated in the following ways:

1. External annotation bodies: only create an annotation, pointing to the external annotation body. Optionally, aggregate the external annotation body in the research object.
2. Internal annotation bodies: only aggregate an annotation body and use the ao:annotatesResource Link header. The service will create the proxy and the annotation automatically and will return the URI of the annotation.
3. Internal annotation bodies, the long way: create an annotation and then upload the annotation body, or the other way round. This is the only method to add an annotation as an annotation body (a rare case). It can als be used to convert an existing aggregated resource into an annotation body.

The example below demonstrates annotating a resource foo/bar.txt using an external annotation body.

The example below demonstrates annotating the same resource using an internal annotation body that will be created as "foo/ann.ttl". Note that the proxy URI for the annotation body is not returned, even though it is created. In this example, the primary operation is POSTing the annotation body to the RO, which causes it to be aggregated, but the Link: header causes the annotation stub to be created that adds this to the set of annotations for the RO.

The example below demonstrates adding an annotation body and then creating the annotation. Note that the use of the resource URI is recommended over using the proxy URI.

Update an annotation

The example below demonstrates updating an existing annotation. Trying to create a new annotation in this way will result in 403 Forbidden.

Get an annotation

When dereferencing an annotation, the client is redirected to the annotation body.

Note that since an annotation body is always an RDF graph, content negotiation is allowed. If you do content negotiation in the first request, you will be redirected to a format-specific resource.

Remove an annotation

Removing an annotation does not remove the annotation body, even if it is an internal resource. For this reason, note that the annotation URI must be used, not the annotation body URI.

Create a folder

Creating a folder is like creating any RO resource, only with a special MIME type: application/vnd.wf4ever.folder. When the folder is created, an RDF/XML graph must be supplied with initial content defined according to the RO model. The folder may aggregate no content initially, in which case an empty aggregation must be sent.

The RDF/XML graph may define ro:FolderEntries for the aggregated resources. If they are not defined, then the service must create them with arbitrary ro:EntryNames (the names under which resources are visible in the ro:Folder). The full RDF description of the folder is returned in response.

A folder will have its proxy created, as any RO resource.

The first folder created in the RO becomes the rootFolder of the RO. If it's deleted, then the next one that is created becomes the new root folder.

Get a folder

When dereferencing a folder, the service may redirect to the RDF file describing the ORE aggregation. The redirection may be based on content negotiation. The service may also return a ZIP file with the ORE aggregation in RDF/XML and some of the resources serialized (informally called "internal" resources).

Delete a folder

A folder can be deleted like any other aggregated resource. All folder entries of this folder will be also deleted but the resources aggregated in the folder will be left intact.

If the folder aggregated another folder, it may happen that the latter becomes orphaned, i.e. aggregated only by the RO. This will lead to the folder being not reachable by traversing the folder structure from the root folder and clients should either delete such orphaned folder or show it as unassigned.

Add a resource to a folder

A resource can be added to a folder only if it is already aggregated by the RO. To do it, a new ro:FolderEntry must be created in the ro:Folder. ro:Folder is a specialization of ore:Proxy and adding it is analogous to adding a resource proxy to the Research Object.

The ore:proxyFor is mandatory. The ro:entryName is optional, and server SHOULD generate it arbitrarily if missing.

Delete a resource from a folder

Deleting a resource from a folder means to de-aggregate it from the folder and leave the resource intact, and is analogous to deleting a resource proxy from a Research Object.

Link relations

service:ros

Full URI is http://purl.org/ro/service/ro/ros. It links the service (service description) with the collection of ROs.

service:zipCreate

Full URI is http://purl.org/ro/service/ro/zipCreate. It links the service (service description) resource to which a ZIP with files and folders can be POSTed to create a new RO.

service:zipUpload

Full URI is http://purl.org/ro/service/ro/zipUpload. It links the service (service description) resource to which a ZIP with a complete RO can be POSTed to store this RO.

ore:aggregates

This relation comes from the ?Research Object Vocabulary Specification v0.1 and is used to indicate that a resource is aggregated by the Research Object. Ore:aggregates links the RO with ro:Resources and with ro:AggregatedAnnotations. It does NOT link it with ore:Proxies and annotation bodies.

ro:annotatesAggregatedResource

This relation comes from the ?Research Object Vocabulary Specification v0.1 and is used to indicate that a resource that is ore:aggregated by the RO is annotated by another resource, called the annotation body.

ao:body

This relation comes from the ?Research Object Vocabulary Specification v0.1 and it links a resource that is an rdfs:Graph (the annotation body) with an annotation. By combining the ro:annotatesAggregatedResource and ao:body, annotation bodies are linked with aggregated resources that they annotate.

ore:proxyFor

The ORE relation links proxies and the resources they represent. It is used for ro:Resources aggregated in ro:ResearchObjects as well as for resources aggregated in ro:Folders.

HTTP methods

The RO SRS API uses four HTTP methods: GET, POST, PUT and DELETE.

GET is used to retrieve the research object and its resources. In case of the research object itself and its metadata, content negotiation is available to get a desired RDF format of the response. Also, in case of research objects, annotations, proxies and folders the client is redirected to the resource that is the representation of each resource.

POST is used to create new content: a new research object, an aggregated resource, an annotation, proxy or a new folder entry. When creating a new annotation or a proxy, it is possible to specify in the request a URI for a resource associated with it (annotation body and proxied resource, respectively), which can be added later if necessary.

PUT is used to update the content or specification of existing resources. In case the URI has been reserved by creating an annotation or a proxy, PUT can also be used for uploading the resource for the first time.

DELETE is used to delete a research object or any other resource.

Resources and formats

The description below is based on ?Research Object Vocabulary Specification v0.1.

A research object aggregates resources and annotations. Each aggregated resource is associated with a proxy that identifies that resource in the context of that research object.

Service description

The RO API service description is an RDF file that contains URI templates for accessing services related to the RO AOI. The RDF syntax used may be content negotiated. In the absence of content negotiation, RDF/XML should be returned.

Example:

Research Object

A Research Object can have 3 different formats, as described in RO dereferencing. These are:

• a ZIP file with all internal resources and metadata.
• an RDF file, i.e. its manifest.
• an HTML page.

Resource

A resource can be any file including even a proxy or an annotation. If the resource is an RDF graph that stores the RO metadata (i.e. the manifest or an annotation body), its content can be retrieved using content negotiation.

Proxy

MIME media type: application/vnd.wf4ever.proxy @@TODO registration

A application/vnd.wf4ever.proxy entity contains an RDF/XML expression that describes one or more ore:Proxy resource. Other information present in the RDF may be ignored. In principle, any RDF data can be used to describe a proxy, but the application/vnd.wf4ever.proxy is currently the only mechanism used for signaling that it is intended to be interpreted as a proxy description.

The ore:Proxy resource type is part of the ORE aggregation structure, and as such is incorporated by reference in the structure of a Research Object. It is described by the ORE abstract model specification (http://www.openarchives.org/ore/1.0/datamodel).

Example:

Annotation

MIME media type: application/vnd.wf4ever.annotation @@TODO registration

A application/vnd.wf4ever.annotation entity contains an RDF/XML expression that describes one or more ro:AggregatedAnnotation resource. Other information present in the RDF may be ignored. In principle, any RDF data can be used to describe a annotation, but the application/vnd.wf4ever.annotation is currently the only mechanism used for signaling that it is intended to be interpreted as an annotation description.

The annotation gets stored in the manifest as ro:AggregatedAnnotation which is a specialization of the AO annotation ontology for the structure of a Research Object.  ao:Annotation is described by the AO model specification (http://code.google.com/p/annotation-ontology/wiki/UnderstandingAO).

Example:

Folder

MIME media type: application/vnd.wf4ever.folder

A application/vnd.wf4ever.folder entity contains an RDF/XML expression that describes one or more ro:Folder resources. Other information present in the RDF may be ignored. The folder description must contain an aggregation of resources. It may also contain ro:FolderEnties for some of the aggregated resources for the purpose of specifying the name of the resource in the folder described.

Example:

Folder entry

MIME media type: application/vnd.wf4ever.folderentry

A application/vnd.wf4ever.folderentry entity contains an RDF/XML expression that describes one or more ro:FolderEntry resources. Other information present in the RDF may be ignored. The folder entry description must contain a ore:proxyFor reference to an aggregated resources. It may contain a reference to the aggregation itself (ore:proxyIn) and the name of the resource in the folder described (ro:entryName).

Example:

Cache considerations

Resources (stored by this service) may be cached provided that they are always validated.

Research objects may be cached as well but their validation depends on the representation:

• for RDF, it is equivalent to validating the manifest
• for a ZIP archive, it requires validating all archive content
• for HTML, the web server settings may be used

Proxies and annotations are effectively stored in the manifest and they redirect to resources of the research object when redirected.

See also:

• http://www.mnot.net/cache_docs/

Security considerations

This service stores data provided by users and allows to manipulate it, so access control is a crucial part of the API.

In order to authorize requests, OAuth 2 should be used. Bearer authorization schema is recommended since it is as simple as possible while providing the necessary security level if used with HTTPS.

Access control policy, i.e. mechanisms of deciding if the request can be performed based on the access token used, is out of scope of this document.

References

• OAuth: http://oauth.net
• OAuth: http://tools.ietf.org/html/rfc6749
• AtomPub:http://tools.ietf.org/html/rfc5023.
• http://www.wf4ever-project.org/wiki/display/docs/RO+model
• http://www.wf4ever-project.org/wiki/display/docs/Research+Object+Vocabulary+Specification
• http://www.wf4ever-project.org/wiki/display/docs/Research+Object+model
• http://www.mnot.net/cache_docs/

See also:

• http://www.wf4ever-project.org/wiki/display/docs/RO+dereferencing