Talia REST Api

Maintainger: Daniel Hahn

See also: Technical specs

This document describes the functions of the TALIA REST service, which provides an remote interface to the library. The interface can be used by other Talia Nodes, users and 3rd-party software.

This document may be incomplete

REST service

Talia REST allows you to read and modify resources in the Talia library by using standard HTTP requests. The client can request different data formats. The service will at least support XML representations of the resources. Optionally, there can also be HTML representations for human consumption.

Types of resources

The REST service allows the client to connect to the different resources stored in the library. The main type of resource is of course the TaliaSource, which can be reached at the URL <NodeRoot?>/<unique id of the source> (for example: http://www.mylibrary/myfirstbook)

Properties of Sources

Each Talia Source can contain any number of "Properties" that belong to that source. A property can either be a simple string (literal value) or a URL that points to another Source. A property can also be a list of Strings or URLs. If the property contains a URL of another source, it is called a "relation".

From the REST point of view, each property has two attributes: First, the property value itself, and second a URI describing the property/relation. (The name of the property/relation will usually be an abbreviation of this URI.)

This means: The name of a property is only a shortcut for the URI that describes the property type!

These properties can be accessed as nested resources (See the documentation at http://www.b-simple.de/documents for more on REST and nested resources) at the URL <NodeRoot?>/<unique id of the source>/<name of the property> (for example: http://www.mylibrary/myfirstbook/author)

Special resources and Source information

Each Talia Source may have some nested resources with reserved names that are read-only. They contain additional information about the Source. For example, there may be <NodeRoot?>/<SourceId?>/data/xxx - which would allow the client to read data from the Source.

Each source will always contain the type information (a list of URIs) and the information about the properties/relations that currently exists (that is a list of properties names, together with the URIs that describe these properties)

Connecting to a Source

To get information about a Source, the client will issue the command

GET <NodeRoot?>/<SourceId?>

and receive an XML representation of the Node. This will contain

  • General information about the Node
  • The list of properties that are available on this node
  • The type information (a list of URIs that describe the ontology types of the node)
  • (Future) Information about the data objects
  • (Future) A signed hash value for integrety checking

POST, PUT and DELETE are not supported on Sources at the moment, since Sources published in the library do not change. (They may be supported in the future for administrative purposes)

Connecting to a Source Property

To get a property of Source, the client will issue the command

GET <NodeRoot?>/<SourceId?>/<property>

This will return a XML representation of that property (URI or literal value), if the property exists in that Source. If the property does not exist, the service will return a useful HTTP response, for example 404.

The client can try to add a new property (usually relations) by issuing the request

POST <NodeRoot?>/<SourceId?>/<property_name>

and give the representation of the data to be added. This operation will require authentication, and the success will be based on the internal policies of the Talia node.

The service should respond to POST requests even if the Source does not have the given property yet. The data for the post request should contain both the property value and the URI that describes this property.

If the property name already exists, but for a different URI than the one that is given, the system should return an error code.

If the property name does not exist, the system can add the new property with the given name or it can choose a different name. In any case, a sensible return code should be returned.

The service will return a useful HTTP status code for the operation.

PUT and DELETE operations are not supported at the moment, because the Sources are immutable once published. (They may be supported in the future for administrative applications)

REST client classes

Talia will contain a REST client classes for ruby, that allows for easy interaction with the REST service. The basic class will work mostly like this:

  • Connecting to a source: rest_source = RESTSource.new("<NodeRoot?>/<SourceId?>")
  • rest_source.types will return an Array of URIs that describe the ontology types used
  • rest_source.properties will return an Array of Strings that describe the properties that exists for that Source at the moment
  • rest_source.<property> will return the value for <property> on the remote source, if it exists. Otherwise, it can raise an error
  • rest_source.<property> = x will try to post the property value to the remote service. This should just return a status code
  • rest_source.property_uri will return the URI that describes the property