TMIP, Topic Map Interaction Protocol 0.3, Specification

Robert Barta

Austrian Research Centers
Smart Systems/Environmental IT


  
  Seibersdorf
  Austria

$Id$

Abstract

This document specifies an interchange protocol based on HTTP which a client can use to retrieve and upload Topic Map specific information.


Table of Contents

Objectives
Scope
Addressing Resources
HTTP Message Headers
MIME Types
Tuple Sequence Encoding
HTTP Methods
GET Complete Maps
GET using TMQL Query
GET Basenames (Using Scopes)
PUT map
POST Map
DELETE Map
OPTIONS Map
GET TMQL Path
PUT TMQL Path (HIGHLY EXPERIMENTAL)
Design Rationale
Bibliography

Objectives

TMIP is a protocol which allows clients to access content from a TM store. It works under the assumption that the store contains topic map instances which are either accessed as a whole or - using TMQL as selection mechanism - in part. The protocol does not assume anything about the storage itself. Maps may be deserialized in memory, may be serialized in textual form using some format, or may even be virtual, i.e. only wrappers around non-Topic Map resources.

TMIP is to satisfy the following requirements:

  • The protocol should be programming language neutral while still allowing platform-specific optimizations.

  • It should adopt the upcoming TM query language [TMQL] in that access be controlled using query expressions.

  • It should support fast bulk retrieval of complete maps and also pinpoint access to fragments thereof. This also includes a certain control of the amount of data to be returned.

  • It should have procurements for update, not only retrieval.

  • It should be RESTful[Fielding02] for reasons of elegance[ArtUNIX03].

It achieves most of this by reusing the mechanics of the HTTP[HTTP] protocol and extending it by a minimum amount of headers and MIME types. It uses only the predefined HTTP methods, GET, POST, PUT and OPTIONS.

Consequently, this specification depends on the following standards:

  • MIME [MIME]
  • HTTP [HTTP]
  • URI [URI]
  • TMQL [TMQL]

and adheres to the Web Architecture[WWWA]. The following documents are only relevant for optional features:

  • LTM spec [LTM]
  • AsTMa= spec [AsTMa=]

Scope

The protocol is assumed to work between a client and a server. The client is always the initiating party. It is outside the scope how the client learns which information can be found on which server.

A server is the connection endpoint to a map store. That stores topic maps (and maybe other information objects) in a hierarchical namespace (section the section called “Addressing Resources”). Topic Map stores are not constrained in the form (representation) of these maps. They can be deserialized in memory, disk or deserialized in any binary or text representation.

Not in the scope of the protocol is authentication. HTTP itself has several authentication mechanisms and implementations may - on top of TMIP - implement their own authentication mechanism (using cookies). Also not in the scope is confidentiality as that is covered by HTTPS.

Following a REST-approach, TMIP is context-free, i.e. subsequent requests have no correlation whatsover. This implies that it is not possible with TMIP itself to implement transactions. Implementations, though, are free to add this facility (e.g. using WebDAV[WebDAV]).

Addressing Resources

All resources are addressed using a URI following the rules in URL[URL] with the additional limitation that the path component follows the grammar:

  path              -> map-selector [ tmql-path-postfix ] 

  map-selector      -> '/' [ /\w+/ map-selector ]

  tmql-path-postfix -> string according TMQL:7.2
      

Examples:

  /xxx/yyy/zzz/            # addresses a whole map

  /xxx/yyy/zzz//aaa/       # addresses all things of type aaa in above map
      

The structure of the map selector implies a hierarchical organisation on the server side. The top-level location has the selector / and is called the root of the map store.

Note

NOTE: /.meta/ is reserved for the server management TM.

Note

NOTE: /.test/ is reserved for testing purposes.

HTTP Message Headers

All messages between client and server follow the structure given by the HTTP protocol. The body of the messages may carry payload; that content type is then specified in the Content-Type header. Relevant for the protocol are:

Content-Type:

Whenever a party sends content in the body, that header will contain the MIME type (see section the section called “MIME Types”). Both, client and server may send content.

Content-Length:

Whenever a party sends content in the body, that header will contain the length of the body. This header is then mandatory.

Accept:

If present, it will contain a list of MIME types acceptable to the client. If required, but not provided, it defaults to text/xml. The server uses these values for content negotiation.

This header will only be used in a request.

Allow:

If present, it will contain a list of MIME types supported by the server. This header will only be used in a successful response to a OPTIONS request.

X-TMIP-Accept-Scope:

This is the only new header. If present, it will contain a list of topic references. The list is separated by commas and may optionally have a trailing entry *. The responding server is requested to use the list of topics as scoping topics, whereby the first topic in the list has precedence over the rest. The * acts as wildcard, implying that any scope is fine.

The topic references follow the syntax tm-item (TMQL:5.8.2). All URIs are resolved against the map selector in the URI of the HTTP message.

MIME Types

The following MIME types are relevant to the protocol:

application/xtm+xml [ optional ]

In an Accept: header in a request message it indicates to the server, that a message with a payload in XTM representation is to be returned. Otherwise, this MIME type may appear in the Content-Type: of any request.

application/x-tmql-sequence+xml [ mandatory ]

In an Accept: header in a request message it indicates to the server, that an XML representation of the requested resource is acceptable. In the Content-Type: header of a message it indicates that the message is an XML document following the structure specified in the section called “Tuple Sequence Encoding”.

application/x-tmql [ mandatory ]

This MIME type can only be used in the Content-Type: header of a request message.

text/x-ltm [ suggested ]

This MIME type is associated with the text format LTM[LTM]. It can be used in the Accept: and the Content-Type: header.

text/x-astma [ suggested ]

This MIME type is associated with the text format AsTMa=[AsTMa=]. It can be used in the Accept: and the Content-Type: header.

application/x-storable [ suggested ]

This MIME type is associated with the serialization provided by the Perl module Storable[Storable]. It can be used in the Accept: and the Content-Type: header.

Tuple Sequence Encoding

The default XML encoding for tuple sequences is defined via RelaxNG[RelaxNG]

default namespace = "http://astma.it.bond.edu.au/ns/tmip/1.0/ts/"
namespace xtm     = "http://www.topicmaps.org/xtm/1.0/"

start   = seq

seq     = element   seq { ordered?, t* }
ordered = attribute ordered { (yes|no) "no" }
t       = element   t   { (id | s | i) }
id      = element   id  { text }
s       = element   s   { text }
i       = element   i   { xtm:* }
      

An <i> element can contain any XTM element according to XTM[XTM].

Example:

<seq xmlns="http://astma.it.bond.edu.au/ns/tmip/1.0/ts/">
   <t>
     <id>firefox</id>....
     <s>Firefox, the Browser</s>
     <i>
        <xtm:topic id="firefox" xmlns:xtm="....">
         <!-- ... -->
        </xtm:topic>
     </i>
   </t>
   <t>
     <id>Mozilla</id>....
     <s>Mozilla</s>
     <i>
        <xtm:topic id="mozilla" xmlns:xtm="....">
         <!-- ... -->
        </xtm:topic>
     </i>
   </t>
</seq>
      

HTTP Methods

TMIP makes use only of the methods GET, OPTIONS, PUT, DELETE and POST. These methods are invoked on the resource identified by the message URI. The message URI is either one which addresses a whole map; consequently the invocation of the method applies to that map. Optionally, the URI may also contain a TMQL path expression additionally to the map location.

All XML content in request bodies must validate against the appropriate schema, or a response code RC_NOT_ACCEPTABLE will be returned by the server. Specifically, application/x-tmql-sequence+xml must validate against the rules in section the section called “Tuple Sequence Encoding” and XTM content must validate against the XTM 1.1 schema[XTM].

As the server is only the gateway to the actual map store, accesses into this store can fail. If this is the case, the server will respond with RC_INTERNAL_ERROR messages.

In the following we list all possible request message scenarios and the appropriate server responses. Any combination not mentioned below is errorenous and will result in a RC_BAD_REQUEST response. Below, a value null for a header or the body means that it is completely ignored by a server.

All messages with a body MUST have a Content-Length: header.

GET Complete Maps

Method:GET
URI: map-selector
Content-Type:null
Accept: list-MIME-types
X-TMIP-Accept-Scope:null
Body:null
Description:

The server will analyze the map-selector location. If that does not exist, then it will return RC_NOT_FOUND. Otherwise, it will iterate over the list-MIME-types and will try to find a representation which it is willing to support (This may be a stored or a computed one). If such exists, then the server will return RC_OK with the appropriate Content-Type: and the whole map representation in the message body. Otherwise it will return RC_UNSUPPORTED_MEDIA_TYPE. If the map representation exceeds a server-side limit, then it may send RC_FORBIDDEN.

GET using TMQL Query

Method:GET
URI: map-selector
Content-Type:application/x-tmql
Accept: list-MIME-types
X-TMIP-Accept-Scope:scope-list
Body:TMQL expression according to TMQL:6
Description:

The server analyzes the map-selector location. If that does not exist, then it will return RC_NOT_FOUND. Otherwise, it will analyze the TMQL expression in the body. If that does not conform to the TMQL specification, the server will return RC_NOT_ACCEPTABLE. Otherwise it will apply the TMQL expression to the map and will compute the results. The list of scoping topics will hereby be passed into the query context. If - during the evaluation - a server-side resource limit is exceeded, then the server may send RC_FORBIDDEN. Then the server will select the first MIME type from the Accept: header which matches the structure of the result value and it is willing to support. If such can be found it will send a response with code RC_OK with an appropriate Content-Type: header and the body containing a serialization of the result. Otherwise it will return RC_UNSUPPORTED_MEDIA_TYPE.

At minimum, the following situations have to be covered:

  • If the query returned a tuple sequence, then the MIME type is application/x-tmql-sequence+xml and the body contains an XML structure representing the tuple sequence.

  • If the query returned an XML structure, then the MIME type used will be text/xml and the body contains the serialized XML structure.

  • If the query returned a map, then the server may choose from the list-MIME-types for a matching format. If that is not supported it may send RC_UNSUPPORTED_MEDIA_TYPE. Otherwise it will create a body with the map content.

GET Basenames (Using Scopes)

Method: GET
URI: map-selector
Content-Type: application/x-tmql-sequence+xml
Accept: application/x-tmql-sequence+xml
X-TMIP-Accept-Scope: scope-list
Body: XML according to the section called “Tuple Sequence Encoding”
Description:

The server will analyze the map-selector location. If that does not exist, it will return RC_NOT_FOUND. Otherwise it will interpret the incoming XML document as tuple sequence with singleton tuples and will interpret all these components of the tuples as topic identifiers. If that fails, it will return RC_NOT_ACCEPTABLE. Otherwise it will return RC_OK with the Content-Type: application/x-tmql-sequence+xml and will send a body containing the XML representation of a tuple sequence with two components each. The first component contains a topic identifier <id> and the second component contains a string containing the base name string of the corresponding topic. The scope-list will hereby be used to resolve a name. If the list is empty (or not given at all), the server will default it to *. For every topic identifier in in the incoming tuple sequence, the scope list will then be iterated over and the first match for a basename will be taken. If there is no such basename for the given scopes, then an empty string will be returned.

The order of the tuple sequence is irrelevant. Servers are allowed to ignore topic identifiers in the incoming sequence which do not identify anything in the addressed map, but otherwise they have to send an entry for each of these identifiers. It is not guaranteed that the returned tuple sequence has the same order than that sent by the client.

PUT map

Method: PUT
URI: map-selector
Content-Type: MIME-type
Accept: null
X-TMIP-Accept-Scope: null
Body: map representation according to MIME-type
Description:

The server will analyze the MIME type of the incoming message. If that is unknown to the server (or it is unwilling to accept), it will send RC_UNSUPPORTED_MEDIA_TYPE. If the size of the request body exceeds a server side limit, it will send RC_REQUEST_ENTITY_TOO_LARGE. Otherwise it will try to analyze the body of the request and will try to interpret this according to its MIME type. If that fails, it will return RC_NOT_ACCEPTABLE. Otherwise it will will store that map under the location map-selector, possibly overwriting an existing version. Then it will return RC_CREATED with an empty body.

POST Map

Method: POST
URI: map-selector
Content-Type: MIME-type
Accept: null
X-TMIP-Accept-Scope: null
Body: map representation according to MIME-type
Description: Same as PUT, but merging instead of replacing.

DELETE Map

Method: DELETE
URI: map-selector
Content-Type: null
Accept: null
X-TMIP-Accept-Scope: null
Description:

The server will analyze the map-selector location. If there is no object at this location, then the server will return RC_NOT_FOUND. If the server is willing to perform a removal of the object there if will return RC_OK with no further information. Otherwise it will return a RC_INTERNAL_ERROR response.

OPTIONS Map

Method: OPTIONS
URI: map-selector
Content-Type: null
Accept: null
X-TMIP-Accept-Scope: null
Description:

The server will analyze the map-selector location. If there is no object on that location, then it will return RC_NOT_FOUND. Otherwise it will return a response with code RC_OK containing a header Allow: which lists all methods which can be used together with this resource. It also may add a header Accept: which lists all MIME types of representations the server is willing to accept for this object.

GET TMQL Path

Method: GET
URI: path
Content-Type: null
Accept: list-MIME-types
X-TMIP-Accept-Scope: scope-list
Body: null
Description:

The server will analyze the map component in the path URI. If the named map does not exist, it will return RC_NOT_FOUND. Otherwise it will analyze the path expression component of the URI. If that does not conform to the TMQL specification (path postfix, TMQL:7.2), the server will return RC_NOT_ACCEPTABLE. Otherwise it will apply the TMQL expression to the map in question. The list of scoping topics will be passed into the query context.

If - during the evaluation - a server-side resource limit is exceeded, then the server may send RC_FORBIDDEN. The server will iterate over the list of acceptable MIME types and will pick one it is willing to support. If there is none, then it will return RC_UNSUPPORTED_MEDIA_TYPE. Otherwise it will send a response with code RC_OK whereby the Content-Type: is set to the supported MIME type and the body contains a serialized form of the tuple sequence.

PUT TMQL Path (HIGHLY EXPERIMENTAL)

Method: PUT
URI: path
Content-Type: application/x-tmql-sequence+xml
Accept: null
X-TMIP-Accept-Scope: scope-list
Body: XML according to the section called “Tuple Sequence Encoding”
Description:

The server will analyze the map component in the /tmql/ URI. If that does not exist, it will return RC_NOT_FOUND. Otherwise it will analyze the path expression in the /tmql/ URI. If that does not conform to the TMQL specification, it will return RC_NOT_ACCEPTABLE. Otherwise it will validate whether the body contains a tuple sequence with singleton values. That sequence MUST be ordered.

It will then apply the path expression to the map in question and will pass in the scope list into the query context.

@@@ HOW TO DO UPDATE @@@

Design Rationale

REST is cool.

Bibliography

Fielding02 (phd-thesis)
bn: Architectural Styles and the Design of Network-based Software Architectures, PhD.
in: University of California, Irvine, 2002
in (author): Fielding R.
oc: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

ArtUNIX03 (book)
bn: The Art of Unix Programming
in (author): Eric Steven Raymond
oc: http://www.faqs.org/docs/artu/

HTTP (rfc)
bn: RFC 2616, HTTP
in (author): R. Fielding, J. Gettys, H. Frystyk, et.al
oc: http://www.faqs.org/rfcs/rfc2616.html

MIME

URI

URL

WebDAV

Storable

RelaxNG


LTM (specification)
bn: LTM, The Linear Topic Map Notation, Lars Marius Garshol, Ontopia A/S
oc: http://www.ontopia.net/download/ltm.html

AsTMa= (specification)
bn: AsTMa= Language Definition, Robert Barta, TechReport, Bond University
oc: http://astma.it.bond.edu.au/astma=-spec-xtm.dbk

TMQL (standards-draft)
bn: Topic Maps Query Language, Working Draft, ISO/IEC JTC1/SC34
in (editors): Lars Marius Garshol, Robert Barta
oc: http://www.isotopicmaps.org/tmql/spec.html

WWWA
bn: WWWA, Architecture of the World Wide Web, Volume One
in (editors): Ian Jacobs, Norman Walsh
oc: http://www.w3.org/TR/webarch/

XTM (standard)
bn @short: XTM 1.1
bn: Topic Maps - XML Syntax, JTC1 / SC34
in (editors): Lars Marius Garshol, Graham Moore
oc: http://www.isotopicmaps.org/sam/sam-xtm/