Version 0.2 – Vancouver Sprint, March 27, 2014

I. Introduction

The DDI 4.0 development effort has identified service-orientation as a goal. This document records the discussion at the Vancouver sprint on this topic, with the idea that it could be used to agree the scope of effort and the needed deliverables to reach the stated goal. While in the past “service-orientation” was usually understood as being an XML-based technology, the advent of RDF and other technologies has expanded this definition beyond traditional XML-based web services.

The intention of this effort was to produce useful work products, but to add as little as practically possible to the DDI 4.0 development workload. Thus, an approach has been identified which would create the minimum set of work products, but which would still help to achieve the goal. The idea is that standard service protocols could allow for the creation of interoperable software components, clients, and dissemination services. It is anticipated that the initial effort will only attempt to provide services for reading sources of DDI, not for read-write scenarios.

II. Protocol and Functions

The decision was taken not to support SOAP-based services at this time, but only to design REST-based services. The following functions were identified.

1.       getIdentifiedObject() – This would allow queries to obtain one or more objects object by passing in a list of one or more identifiers.

2.       getListOfVersions() – This would provide a list of available versions for an identified object, in the form of a list of version-specific identifiers.

3.       getObjectsByType() – This would allow all of the available objects of  a specified type to be obtained, with the response being either the full set of objects or a list of their ids. getSubsetOfObjects() – This would allow for the parameterized search for objects of a stated type, using a syntax like [Object_Type] + [Property] + [Value_List]… or [Relationship] + [ID_of_Target] (or something like that – we want a generic syntax based on the model, not on the XML or RDF structures). This might be as simple as a single key/value pair,  or possibly more.

4.       getListOfRelatedObjects() – This would allow for a list of the IDs and types of objects which are related to a specified object, including specification of how many relationships to include in the result set. It should be possible to ask both for the objects used by the specified object, and also those objects which use it.

5.       getMeADrink() – This was requested by Achim at the end of a long day of sprinting in sub-zero temperatures. Dan proposed to repeat this until a denial of service was achieved.

The return types for these queries would use either the standard DDI XML syntax for the possible objects (basically, xs:any within the DDI 4.0 namespace), or, in the case of getListOfVersions and getListOfRelatedObjects an XML format we would design as a standard document type to use for the service response. If RDF was desired instead (although we are not sure this would be useful given technology developments external to the DDI community), content negotiation would be used to determine the format of the returned metadata, as well as the version of DDI to be returned.

III. Standard Errors

We would define a set of standard errors to be returned by a service, including such things as “function not supported” or “object type not supported,” so that client services could handle common failure cases gracefully. The SDMX Web Service guidelines could be used as a basis for identifying what standard errors are useful.

IV. Deliverables

The deliverables for the service-oriented aspects of DDI 4.0 would include:

(1)    Specification of the RESTful interfaces for each function, including WADL descriptions.

(2)    Specification of all needed XML formats which are not already being developed.

(3)    Specification of standard error codes.