Web Services

From SDMX2 Global Registry Documentation
Jump to: navigation, search

Global Registry Web Services

Introduction

The Registry hosts web services for submission and query of structures. There are four ways of using the Web Services in the Global Registry for the submission of SDMX-ML and SDMX-EDI files.

Web Service Interface Method Used By Supports
Using RESTful POST Applications SDMX-ML Structure messages, SDMX-EDI messages, SDMX-ML Registry Interface Messages
Using RESTful GET Applications SDMX-ML queries
Using SOAP messaging Applications SDMX-ML queries, SDMX-ML Structure messages, SDMX-EDI messages, SDMX-ML Registry Interface Messages
Using the Registry GUI to upload files Individuals SDMX-ML queries, SDMX-ML Structure messages, SDMX-EDI messages, SDMX-ML Registry Interface messages


The Registry supports the SDMX REST query API. In addition the GUI has an interactive screen that will build a REST query from user selections. The GUI will return the Registry response in SDMX-ML. This is useful for learning the syntax of the SDMX REST API and the types of selection available.

Available Web Services

Web Service URLs

The Registry hosts 4 web services. Each can consume any format of SDMX, but each responds in either SDMX version 1.0, 2.0, 2.1 or EDI. The actual web service URLs are:

• http://[server]:[port]/FusionRegistry/ws/restInterfaceV1

• http://[server]:[port]/FusionRegistry/ws/restInterfaceV2

• http://[server]:[port]/FusionRegistry/ws/restInterfaceV2_1

• http://[server]:[port]/FusionRegistry/ws/restInterfaceEDI

POSTing a document via an External Application

To POST a document from machine code, ensure the content-type HTTP header is set to “application/text” and set “Accept-Encoding” to “gzip” if the application is able to support compressed responses.

Example Java Code for POSTing a document to the Global Registry

String webService = "http://www.sdmxregistry.org/FusionRegistry/ws/restInterfaceV2_1";

URL url = new URL(webService);

URLConnection urlc = url.openConnection();

urlc.setDoOutput(true);

urlc.setAllowUserInteraction(false);

urlc.addRequestProperty("Content-Type", "application/text");

PrintStream ps = new PrintStream(urlc.getOutputStream());

ps.print(xml);

ps.close();

InputStream response = urlc.getInputStream();

Example Java Code for calling REST (HTTP GET) for the Global Registry

String restQuery = "http:// www.sdmxregistry.org /FusionRegistry/ws/restInterfaceV2_1/codelist/ALL/ALL/ALL";

URL url = new URL(restQuery);

URLConnection urlc = url.openConnection();

urlc.setDoOutput(true);

urlc.setAllowUserInteraction(false);

InputStream response = urlc.getInputStream();

Auto Increment Version Web Service

There is an additional web service which can consume any format of SDMX and responds in SDMX version 2.1. The additional functionality provided by the auto increment web service is that it will automatically increment version numbers of submitted structures when these structures already exist. The auto increment rules are as follows:

  1. If a structure is submitted that does not yet exist in the Registry no action is taken.
  2. If the structure exists already then the version number of the submitted structure is incremented, and the existing structure in the Registry remains unchanged.
  3. A minor version increment is performed if the structure does not differ in the identifiable composite structures. For example, a submitted code list with exactly the same codes (a code is identifiable as it has a URN) will be given a minor version increment.
  4. A major increment is performed if the submitted structure has an additional identifiable or has had an identifiable removed. For example a codelist may have had a code removed.
  5. A minor version increment is a .1 increase. For example 1.2 becomes 1.3 (or 1.3.2 becomes 1.4).
  6. A major version increment is a full integer increase. For example version 1.0 becomes 2.0 (or 1.4 becomes 2.0).
  7. Any structures which cross reference the existing structure will also have a minor version increment and the references will be updated to reference the latest structure. This rule is recursive, so any structures that reference the references are also updated. This rule will also apply if the referenced structure is in the same structure submission, as long as the referencing structure in the submission has had its version modified.

This auto increment web service is available at the following location:

http://[server]:[port]/FusionRegistry/ws/restInterfaceAuto

Using the Registry GUI

To Upload Structures

The Registry GUI can be used to upload SDMX_ML, SDMX-EDI or, for code lists, CSV files, containing structural metadata. See File Upload

For Creating a REST Query

A web service query can be created with help from the GUI. Select 'Web Service' from the Main Menu to be presented with the Web Service query creation page.

Web services build structure query.png

This page is split into two sections. The top section is for a structure query and the lower section is for a schema query.

In each section, a REST URL is generated from the values specified by the controls within that section. The URL is displayed at the bottom of the section and can be copied to the clipboard (by clicking on the icon to the right of the URL), or it can be opened in a new window (by clicking on the Open button). Opening the URL in a new window will result in the query being run against the Registry and the results will be displayed in the browser window.

NOTE: most web browsers will not know how to display an SDMX-EDI response, and the browser may display an error message. In this instance right-click on the page, and choose 'view page source' to view the SDMX-EDI.