One of the goals of the Web3 Platform was to adhere to as many of the architectural principles of REST that was possible. In our minds the key things were that:

1) Given a start URI and a description of all the content types and valid transitions a client could interact with the topic map store.

Yep, there is only that one point.

Given the URI of a topic map a client that is aware of the different content types that can be returned can interact with the entire topic map without guessing at, or constructing URIs.

For the Web3 Platform we introduced a new syntactic representation for Topic Maps because XTM is an interchange syntax for Topic Maps and not an effective Hypertext representation for the TMDM.

I’ll walk through some interactions starting from a topicmap URL to demonstrate why we introduced the new syntax and how a client behaves.

Starting with the topicmap URL:

[code]

GET http://localhost/web3/topicmaps/e518129d-b458-4171-99cc-5e4941dafc7b?format=xml

[/code]

When addressing Web3 Resources content negotiation can be done through accept headers or via  a format parameter. The above GET returns the following representation.

[code]

[/code]

There are a couple of things to notice in this representation.

  1. We use full URLs for everything, no Ids that need turning into URLs based on some defined URL space.
  2. We are exposing the collections of Topics and Associations as resources in their own right. This allows clients to POST to these collections to create new Topics and Associations and also to fetch these collections. (The full representation documentation also specifies the allowed query parameters for these resources).

Now a client can navigate the topic collection using:

[code]

GET http://localhost/web3/topicmaps/e518129d-b458-4171-99cc-5e4941dafc7b/topics?format=xml

[/code]

This returns the following collection:

[code]

[/code]

The interesting things in the snippet above are:

  1. We have introduced a generic list container for topics, in fact topic refs. This gives us control over thing like collection size and paging.
  2. We have introduced a lightweight topic reference structure for use in listing topics. This is a subset of the full topic representation and is used in many places.
  3. We are explicit about the topic's web address.
  4. We provided explicit links to navigate through the collection
    5. All of the above means that a client who understands this content type can navigate to a topic, and find more results or the previous page of results. Following a link to a topic using: [code] GET http://localhost/web3/topicmaps/e518129d-b458-4171-99cc-5e4941dafc7b/topics/2a8a2182-f8b7-427a-9f7f-ef206b775606?format=xml [/code] Returns the following XML [code] http://localhost/web3/schemas/0df562f3-f86b-4fbb-a4d3-66679f2df0fa/types/16f22191-5fd7-4f15-8014-f4fc28b1563e http://www.myfilms.com/types/person http://www.myfilms.com/types/biography http://localhost/web3/schemas/0df562f3-f86b-4fbb-a4d3-66679f2df0fa/types/45ba8b1a-a80c-40c6-8fb6-7d1692c0da7b Born in the 1940's [/code] Points of interest in the above snippet are:
    1. The link to the associations for the topic. With this we have created a resource that can be navigated to return the associations in which the topic plays a role. (There are optional query parameters on this as well.)
    2. We use inline topic ref elements to minimise round trips for common things, such as property types and topic types.
    3. All contained resources, property (is name or occurrence) and identity expose their web address.
    4. We have also included version information to help with ETag processing.
    Finally, following the associations link using: [code] http://localhost/web3/topicmaps/e518129d-b458-4171-99cc-5e4941dafc7b/topics/2a8a2182-f8b7-427a-9f7f-ef206b775606/associations?format=xml [/code] We get back the following XML structure: [code] http://psi.topicmaps.org/iso13250/model/type-instance http://psi.topicmaps.org/iso13250/model/instance http://localhost/web3/schemas/0df562f3-f86b-4fbb-a4d3-66679f2df0fa/types/16f22191-5fd7-4f15-8014-f4fc28b1563e http://www.myfilms.com/types/person http://psi.topicmaps.org/iso13250/model/type [/code] So the key things we wanted to do was to create a set of content types that along with a description allowed a client to interact with a Topic Map without the need to refer to or know how to generate ANY URIs. The examples above have shown how we have updated the core TMDM items, topic, association, occurrence etc to be better REST citizens, and we have also introduced new resources for collections of things in the topic map model. These collections are key to connecting together the basic topic map building blocks. The full content type descriptions, including update semantics, are available as part of the documentation for the Web3 Platform. You can request an evaluation copy of the software here. We also recently posted about how we support transactions in a RESTful way.