Difference between revisions of "REST API Overview"

From FMR Knowledge Base
Jump to navigation Jump to search
(→‎Implementation of the SDMX REST API in Fusion Registry)
(→‎Authentication)
 
(48 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
[[Category:FMR_REST_API_Reference]]
 
[[Category:FMR_REST_API_Reference]]
−
 
 
=SDMX Standard REST API Specification=
 
=SDMX Standard REST API Specification=
  
Line 16: Line 15:
 
* A distinction should be established between the elements that allow identifying the resource to be retrieved and the elements that give additional information about, or allow to further filter, the desired results. Elements belonging to the 1st category are specified in the path part of the URL while elements belonging to the 2nd category are specified in the query string part of the URL.
 
* A distinction should be established between the elements that allow identifying the resource to be retrieved and the elements that give additional information about, or allow to further filter, the desired results. Elements belonging to the 1st category are specified in the path part of the URL while elements belonging to the 2nd category are specified in the query string part of the URL.
  
−
==Implementation of the SDMX REST API in Fusion Registry==
+
==Implementation of the SDMX REST API in Fusion Metadata Registry==
 
Fusion Metadata Registry is primarily concerned with structural metadata so implements a subset of the SDMX RESTful API specification.
 
Fusion Metadata Registry is primarily concerned with structural metadata so implements a subset of the SDMX RESTful API specification.
  
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
! REST API Function !! Implemented  
+
! SDMX REST API Function !! Implemented  
 
|-
 
|-
 
| Structural Metadata Queries || style="backgroundcolor:red;" | YES
 
| Structural Metadata Queries || style="backgroundcolor:red;" | YES
 
|-
 
|-
−
| Schema Queries || YES
+
| Schema Queries (for retrieving SDMX-ML Structure Specific Data validation schemas) || YES
 
|-
 
|-
 
| Data Queries || NO
 
| Data Queries || NO
Line 53: Line 52:
 
|}
 
|}
  
−
== Structural Metadata Queries ==
+
= Structural Metadata Queries =
 +
 
 +
A structural metadata query uses HTTP GET with the following general URL syntax:
 +
<pre>http(s)://ws-entry-point/resource/agencyID/resourceID/version</pre>
  
 
=== Resources ===
 
=== Resources ===
Line 117: Line 119:
  
 
{| class="wikitable"
 
{| class="wikitable"
−
!width="5%"| Keywords
+
!Keywords !! Scope !! Description
−
!width="5%"| Scope
 
−
!width="5%"| Description
 
 
|-
 
|-
 
| all
 
| all
Line 143: Line 143:
  
 
* If no version is specified, the version currently used in production should be returned. It is therefore equivalent to using the keyword <code>latest</code>.
 
* If no version is specified, the version currently used in production should be returned. It is therefore equivalent to using the keyword <code>latest</code>.
−
* If no agencyID is specified, the matching artefacts maintained by any maintenance agency should be returned. It is therefore equivalent to using the keyword <code>all</code>. This would potentially return more than one artefact, if different agencies give the same identifier to a resource (for example, http://ws-entry-point/codelist/all/CL_FREQ, could return more than one codelist if more than one agency is maintaining a codelist with id &quot;CL_FREQ&quot;).
+
* If no agencyID is specified, the matching artefacts maintained by any maintenance agency should be returned. It is therefore equivalent to using the keyword <code>all</code>. This would potentially return more than one artefact, if different agencies give the same identifier to a resource (for example, <nowiki>http://ws-entry-point/codelist/all/CL_FREQ</nowiki>, could return more than one codelist if more than one agency is maintaining a codelist with id &quot;CL_FREQ&quot;).
 
* If no resourceID is specified, all matching artefacts (according to the other criteria used) should be returned. It's is therefore equivalent to using the keyword <code>all</code>.
 
* If no resourceID is specified, all matching artefacts (according to the other criteria used) should be returned. It's is therefore equivalent to using the keyword <code>all</code>.
 
* If no parameters are specified, the '''latest''' version of '''all''' resources of the type identified by the resource parameter, maintained by '''any''' maintenance agency should be returned.
 
* If no parameters are specified, the '''latest''' version of '''all''' resources of the type identified by the resource parameter, maintained by '''any''' maintenance agency should be returned.
Line 313: Line 313:
 
<li><p>To retrieve the category PRICES of the DOMAINS category scheme maintained by the ECB, as well as the categorisations referencing that category:</p>
 
<li><p>To retrieve the category PRICES of the DOMAINS category scheme maintained by the ECB, as well as the categorisations referencing that category:</p>
 
<pre>http://ws-entry-point/categoryscheme/ECB/DOMAINS/latest/PRICES?references=categorisation</pre></li>
 
<pre>http://ws-entry-point/categoryscheme/ECB/DOMAINS/latest/PRICES?references=categorisation</pre></li>
−
<li><p>To retrieve the latest version of the CL_FREQ codelists maintained by the BIS or the ECB: http://ws-entry-point/codelist/BIS+ECB/CL_FREQ</p></li></ul>
+
<li><p>To retrieve the latest version of the CL_FREQ codelists maintained by the BIS or the ECB: <nowiki>http://ws-entry-point/codelist/BIS+ECB/CL_FREQ</p></li></ul></nowiki>
−
 
 
−
 
 
  
−
== Schema queries ==
+
= Schema queries =
  
 
=== Resources ===
 
=== Resources ===
Line 405: Line 403:
 
<p>In this case, the schema returned by the service must take into account the constraints attached to the provision agreement, the dataflow used in the provisionagreement and the data structure definition used in the dataflow.</p></li></ul>
 
<p>In this case, the schema returned by the service must take into account the constraints attached to the provision agreement, the dataflow used in the provisionagreement and the data structure definition used in the dataflow.</p></li></ul>
  
−
==Structure Submission==
+
=Structural Metadata Submission=
 +
Structural metadata can be added or modified by using <strong>HTTP POST</strong> to submit any valid SDMX Structure Document to the secure API.
 +
 
 +
====Resource====
 +
<pre>protocol://domain/ws/secure/sdmxapi/rest</pre>
 +
<nowiki>Example: https://registry.mydomain.org/FusionRegistry/ws/secure/sdmxapi/rest</nowiki>
 +
 
 +
====Authentication====
 +
Only authenticated users with sufficient Agency or Admin privileges can modify structural metadata content. HTTP Basic Authentication must be used to with this service.
  
−
=Fusion Metadata Registry Extended REST API=
+
====Actions====
−
==Data Validation==
+
The following actions can be specified when submitting structural metadata content.
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Entry Point</b>|| <b> /ws/public/data/validate </b>
+
! Action !! Behaviour
−
|-
 
−
|style="background-color:#eaecf0"|<b>Access</b>|| <span style='color:green'><b>Public</b></span> (default). Configurable to Private
 
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Http Method</b>|| POST
+
| Append || New maintainable structures are added, but an error occurs if any of the structures submitted already exist in the Registry
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Accepts</b>|| CSV, XLSX, SDMX-ML, SDMX-EDI (any format for which there is a Data Reader)
+
| Replace || Existing maintainable structures are replaced in their entirety and new ones added if needed
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Compression</b> || Zip files supported, if loading from URL gzip responses supported
+
| Merge || Similar to Append except items are added to existing item schemes - useful for adding Codes to Codelists
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Content-Type</b>|| <p>1. multipart/form-data (if attaching file) – the attached file must be in field name of uploadFile</p>
+
| FullReplace || The entire contents of the Registry are replaced with the structures submitted
−
<p>2. application/text or application/xml (if submitting data in the body of the POST)</p>
 
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Response Format</b>|| application/json
+
| Delete || The maintainables identified in the submitted content are deleted
−
|-
 
−
|style="background-color:#eaecf0"|<b>Response Statuses</b>|| <p><b>200</b> - Validation could be performed</p>
 
−
<p><b>400</b> - Validation could not be performed (either an unreadable dataset, or unresolvable reference to a required structure)</p>
 
−
<p><b>401</b> - Unauthorized (if access has been restricted)</p>
 
−
<p><b>500</b> - Server Error</p>
 
 
|}
 
|}
  
−
=== HTTP Headers ===
+
====Submission Content Options====
 +
The following SDMX Structure Documents can be submitted in the body of the POST:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
!|HTTP Header || Purpose || Allowed Values
+
! Message Type !! Action
−
|-
 
−
|style="background-color:#eaecf0"|<b>Data-Format</b>|| Used to inform the server when the data is in CSV format. ||csv;delimiter=[delimiter]
 
−
<p>Where [delimiter] is either:</p>
 
−
<ul>
 
−
<li>comma</li>
 
−
<li>tab</li>
 
−
<li>semicolon</li>
 
−
<li>space</li>
 
−
</ul>
 
−
|-
 
−
|style="background-color:#eaecf0"|<b>Structure</b> || <p>(optional) Provides the structure to validate the data against.</p>
 
−
 
 
−
<p>This information may be present in the header of the dataset, if provided this value will override the value in the dataset.</p>
 
−
<p>Fusion Registry v10.4.7 onwards accepts a comma separated list of URNs if multiple datasets exist in the loaded file, however if multiple URNs are provided, URN must be of a Dataflow or Provision Agreement and the datasets must identify at a minimum the Data Structure that is needed to read the file.</p>
 
−
 
 
−
|| Valid SDMX URN for Provision Agreement, Dataflow, or Data Structure Definition
 
−
|-
 
−
|style="background-color:#eaecf0"|<b>Inc-Metrics</b><p style="font-size:0.85em">(Since v9.8)</p>||
 
−
<p>Optional. Includes metrics on the validation.</p>
 
−
<p>This will add extra detail to the validation report.</p>
 
−
||Boolean (true/false)
 
−
|-
 
−
|style="background-color:#eaecf0"|<b>Inc-Valid</b><p style="font-size:0.85em">(Since v9.8)</p>||<p>Optional. Instructs the service to include a dataset with all the valid series and observations in the response.</p> 
 
−
 
 
−
<p>As the result will contain a separate file for the dataset, the response format will be set to either multipart/mixed message with a boundary per file, or if the Zip header is set to true, the output will be a single zip file.</p>
 
−
<p>The file is called ValidData with the file extension based on the output format.</p>
 
−
||Boolean (true/false)
 
−
 
 
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Inc-Invalid</b><p style="font-size:0.85em">(Since v9.8)</p>||<p>
+
| SDMX-ML Structure Message || Specify the action using the HTTP 'Action' header (default is Replace)
−
Optional. Instructs the service to include a dataset with all the invalid series and observations in the response.  </p>
 
−
 
 
−
<p>As the result will contain a separate file for the dataset, the response format will be set to either multipart/mixed message with a boundary per file, or if the Zip header is set to true, the output will be a single zip file.</p>
 
−
<p>The file is called InvalidData with the file extension based on the output format.</p>
 
−
 
 
−
||Boolean (true/false)
 
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Accept</b><p style="font-size:0.85em">(Since v9.8)</p>||<p>Optional. Instructs the service which data output format to output the valid or invalid datasets in.
+
| SDMX-JSON Structure Message || Specify the action using the HTTP 'Action' header (default is Replace)
−
</p>
 
−
<p>This Header is only used if Inc-Valid or Inc-Invalid are set to true.</p>
 
−
||[[Data_Formats|See Accept Formats]]
 
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Zip</b><p style="font-size:0.85em">(Since v9.8)</p>||Optional. Compresses the output as a zip file.  If used in conjunction with <b>Inc-Valid</b> or <b>Inc-Invalid</b> the zip will contain multiple files.
+
| SDMX-EDI (GESMES) Structure Message || Specify the action using the HTTP 'Action' header (default is Replace)
−
||Boolean (true/false)
 
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Prior-Data-Dependent</b><p style="font-size:0.85em">(Since v9.8)</p>||<p>
+
| SDMX-ML SubmitStructureRequest Registry Interface Message || Specify the action using the 'Action' header in the message
−
Optional. This allows data to be validated under the assumption that other data will provide missing information.  If this value is set to true, particular data validators will not be used when validating the data. These validators are "Mandatory Observations" and "Valid Calculations".</p>
 
−
 
 
−
<p>Default value is false.</p>
 
−
 
 
−
||Boolean (true/false)
 
 
|}
 
|}
  
−
=== Response ===
+
The content can be Zipped, and multi-part submissions are also accepted.
−
<p>
 
−
The validation output contains both human readable error descriptions, as well as machine processible locations of the errors within the dataset.  The location in the dataset is described as a key or observation locator in the format; A:UK:M:2008 – where each component relates to the Dimension value, separated by a colon.  If the error position is observation, the last part of the key is the observation time period.</p>
 
−
 
 
−
<p>Since Fusion Registry 10.5.4, error code values are output, which provide a unique code for each type of error. For a list of the error codes, refer to [[Error Codes | error codes]].
 
−
 
 
−
<p>There are 3 types of output that can be produced which share a common structure: unable to parse input(returns HTTP 400); able to parse input but references invalid data structure (returns HTTP 200); parsed input and returns output, which may have validation errors (return HTTPS 200). Below are examples of each:</p>
 
−
 
 
−
=== Valid Dataset ===
 
  
−
{
+
====Response====
−
  "Meta": {
+
A successful submission results in a SDMX-ML SubmitStructureResponse message.
−
    "RequestTime": 1564410081711,
+
If an error occurs, a SDMX-ML ErrorResponseDocument is returned.
−
    "Duration": 43
 
−
  },
 
−
  "FileFormat": "Structure Specific (Compact) v2.1",
 
−
  "Prepared": "2019-07-29T10:23:01",
 
−
  "SenderId": "FR_DEMO",
 
−
  "DataSetId": null,
 
−
  "Status": "Complete",
 
−
  "Errors": false,
 
−
  "Datasets": [
 
−
    {
 
−
      "DSD": "urn:sdmx:org.sdmx.infomodel.datastructure.DataStructure=OECD:HIGH_AGLINK_2011(1.0)",
 
−
      "Dataflow": "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=OECD:AGRIC_OUTLOOK_2011_2020(1.0)",
 
−
      "DataProvider": "urn:sdmx:org.sdmx.infomodel.base.DataProvider=METATECH:DATA_PROVIDERS(1.0).METATECH",
 
−
      "ProvisionAgreement": "urn:sdmx:org.sdmx.infomodel.registry.ProvisionAgreement=OECD:OECD_AGRIC_OUTLOOK(1.0)",
 
−
      "KeysCount": 2,
 
−
      "ObsCount": 62,
 
−
      "GroupsCount": 0,
 
−
      "Errors": false
 
−
      "ReportedPeriods": {
 
−
      "A": {
 
−
          "Name": "Annual",
 
−
          "StartPeriod": "1990",
 
−
          "EndPeriod": "2020"
 
−
        }
 
−
      },
 
−
    }
 
−
  ],
 
−
  "PreventsConversion": false,
 
−
  "PreventsPublication": false
 
−
}
 
  
 +
=Structure Deletion=
 +
The simplest way to delete Structural Metadata is using the <strong>HTTP DELETE</strong> verb.
  
−
=== Dataset with Errors ===
+
====Resources====
−
{
+
Deletion of structures uses the same resources as [[REST_API_Overview#Structural_Metadata_Queries|Structural Metadata Queries]] to identify precisely what to delete.
−
  "Meta": {
 
−
    "RequestTime": 1564401209760,
 
−
    "Duration": 34
 
−
  },
 
−
  "InvalidData": {
 
−
    "Datasets": [
 
−
      {
 
−
        "Structure": "urn:sdmx:org.sdmx.infomodel.registry.ProvisionAgreement=OECD:OECD_AGRIC_OUTLOOK(1.0)",
 
−
        "Series": 2,
 
−
        "Observations": 61,
 
−
        "Groups": 0
 
−
      }
 
−
    ]
 
−
  },
 
−
  "ValidData": {
 
−
    "Datasets": [
 
−
      {
 
−
        "Structure": "urn:sdmx:org.sdmx.infomodel.registry.ProvisionAgreement=OECD:OECD_AGRIC_OUTLOOK(1.0)",
 
−
        "Series": 2,
 
−
        "Observations": 32,
 
−
        "Groups": 0
 
−
      }
 
−
    ]
 
−
  },
 
−
  "FileFormat": "Structure Specific (Compact) v2.1",
 
−
  "Prepared": "2019-07-29T10:23:01",
 
−
  "SenderId": "FR_DEMO",
 
−
  "DataSetId": null,
 
−
  "Status": "Complete",
 
−
  "Errors": true,
 
−
  "Datasets": [
 
−
    {
 
−
      "DSD": "urn:sdmx:org.sdmx.infomodel.datastructure.DataStructure=OECD:HIGH_AGLINK_2011(1.0)",
 
−
      "Dataflow": "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=OECD:AGRIC_OUTLOOK_2011_2020(1.0)",
 
−
      "DataProvider": "urn:sdmx:org.sdmx.infomodel.base.DataProvider=METATECH:DATA_PROVIDERS(1.0).METATECH",
 
−
      "ProvisionAgreement": "urn:sdmx:org.sdmx.infomodel.registry.ProvisionAgreement=OECD:OECD_AGRIC_OUTLOOK(1.0)",
 
−
      "KeysCount": 3,
 
−
      "ObsCount": 93,
 
−
      "GroupsCount": 0,
 
−
      "ReportedPeriods": {
 
−
        "A": {
 
−
              "Name": "Annual",
 
−
              "StartPeriod": "1990",
 
−
              "EndPeriod": "2020"
 
−
        }
 
−
      },
 
−
      "Errors": true,
 
−
      "ValidationReport": [
 
−
      {
 
−
          "Type": "Constraint",
 
−
          "Errors": [
 
−
            {
 
−
              "ErrorCode": "REG-201-250",
 
−
              "Message": "Disallowed Dimension Value: REF_AREA=AFR",
 
−
              "Dataset": 0,
 
−
              "ComponentId": " REF_AREA ",
 
−
              "ReportedValue": "AFR",
 
−
              "Position": "Series",
 
−
              "Keys": ["AFR:BT:AA"]
 
−
            }
 
−
          ]
 
−
        },
 
−
        {
 
−
          "Type": "Representation",
 
−
          "Errors": [
 
−
          {
 
−
            "ErrorCode": "REG-201-200",
 
−
            "Message": "Dimension 'VARIABLE' is reporting value 'AA' which  is not a valid representation in referenced Codelist 'OECD:CL_HIGH_AGLINK_2011_VARIABLE(1.0)'",
 
−
            "Dataset": 0,
 
−
            "Position": "Series",             
 
−
            "ComponentId": "VARIABLE",
 
−
            "ReportedValue": "AA",
 
−
            "Keys": ["AFR:BT:AA"]
 
−
          },
 
−
          {
 
−
            "ErrorCode": "REG-201-201",
 
−
            "Message": "Error in Primary Measure 'OBS_VALUE': Reported value 'XXX' is not of expected type 'Double'",
 
−
            "Dataset": 0,             
 
−
            "ComponentId": " OBS_VALUE",
 
−
            "ReportedValue": "XXX",
 
−
            "Position": "Observation",
 
−
            "Keys": ["AFR:BT:IM:2010"]
 
−
          }
 
−
          ]
 
−
        },
 
−
        {
 
−
          "Type": "FormatSpecific",
 
−
          "Errors": [
 
−
            {
 
−
            "Message": "Unexpected attribute 'ASD' for element 'StructureSpecificData/DataSet/Series/Obs'",
 
−
            "Dataset": 0,
 
−
            "Position": "Dataset"
 
−
          }
 
−
          ]
 
−
        }
 
−
      ]
 
−
    }
 
−
  ],
 
−
  "PreventsConversion": false,
 
−
  "PreventsPublication": true
 
−
}
 
  
−
<p>Note the first three elements ‘Meta’, ‘InvalidData’, ‘ValidData’, there are present in the report if Inc-Metrics is set to true.  Inc-valid and Inc-Invalid set to true enables the report to know the metrics for the invalid and valid data.</p>
+
Maintainables
−
<p>Note also each Error has a Type, this is the category of error which caused the validator to fail. For a list of all validators see the following section on Validators.
+
<pre>protocol://domain/ws/secure/sdmxapi/rest/resource/agencyID/resourceID/version</pre>
−
The Error Position is either set to Dataset, Series, Observation, or Group. </p>
+
Example:<br>  
−
<p>PreventsConversion and PreventsPublication is an indication on the severity of the error.  These settings on which errors prevent conversion and publication can be set in the Fusion Registry by the administrator of the system.</p>
+
<nowiki>https://registry.mydomain.org/ws/secure/sdmxapi/rest/datastructure/ECB/ECB_TRD/1.0</nowiki><br>
  
−
=== Dataset with an Unresolvable Datset Reference ===
+
Items
−
{
+
<pre>protocol://domain/ws/secure/sdmxapi/rest/resource/agencyID/resourceID/version/itemID</pre>
−
  "FileFormat": "Generic v2.1",
+
Examples:<br>
−
  "MimeType": "application/xml",
+
<nowiki>https://registry.mydomain.org/ws/secure/sdmxapi/rest/codelist/ECB/CL_FREQ/1.0/A</nowiki><br>
−
  "Status": "InvalidRef",
+
<nowiki>https://registry.mydomain.org/ws/secure/sdmxapi/rest/codelist/ECB/CL_FREQ/1.0/A+M+Q</nowiki><br>
−
  "Errors": true,
 
−
  "Datasets": [{"Dataflow": "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=BIS:INVALID_DATAFLOW(1.0)"}]
 
−
}
 
−
<p><b>Errors</b> has a value of true, the <b>Status</b> states InvalidRef, and the <b>Datasets</b> provides the reported reference which could not be resolved</p>
 
  
−
=== Dataset which could not be read ===
+
====Authentication====
−
{
+
Only authenticated users with sufficient Agency or Admin privileges can modify structural metadata content. HTTP Basic Authentication must be used to with this service.
−
  "Status": "Error",
 
−
  "Errors": true,
 
−
  "Error": "Unexpected '<' character in element (missing closing '>'?)\r\n at [row,col {unknown-source}]: [17,3]"
 
−
}
 
−
<p>This error will be reported when the Fusion Registry is unable to determine what type of data the dataset is, so is unable to process the dataset for validation</p>
 
  
−
==Data Transformation==
+
====Response====
 +
A successful submission results in a SDMX-ML SubmitStructureResponse message.
 +
If an error occurs, a SDMX-ML ErrorResponseDocument is returned.

Latest revision as of 23:55, 4 July 2022

SDMX Standard REST API Specification

Scope of the SDMX REST API

The RESTful API focuses on simplicity. The aim is not to replicate the full semantic richness of the SDMX-ML Query message but to make it simple to perform a limited set of standard queries. Also, in contrast to other parts of the SDMX specification, the RESTful API focuses solely on data retrieval (via HTTP GET). More specifically, the API allows:

  • To retrieve structural metadata, using a combination of id, agencyID and version number.
  • To retrieve statistical data or reference metadata using keys (with options for wildcarding and support for the OR operator), data or metadata flows and data or metadata providers.
  • To further refine queries for statistical data or reference metadata using time information (start period and end period).
  • To retrieve updates and revisions only.
  • To return the results of a query in various formats. The desired format and version of the returned message will be specified using HTTP Content Negotiation (and the HTTP Accept request header).
  • For structural metadata, it is possible to instruct the web service to resolve references (for instance, when querying for data structure definitions, it is possible to also retrieve the concepts and code lists used in the returned data structure definitions), as well as artefacts that use the matching artefact (for example, to retrieve the dataflows that use a matching data structure definition).
  • For structural metadata, it is possible to retrieve a minimal version of the artefact, for the sake of efficiency (for example, to retrieve all code lists – names, ids, etc – without the codes).
  • A distinction should be established between the elements that allow identifying the resource to be retrieved and the elements that give additional information about, or allow to further filter, the desired results. Elements belonging to the 1st category are specified in the path part of the URL while elements belonging to the 2nd category are specified in the query string part of the URL.

Implementation of the SDMX REST API in Fusion Metadata Registry

Fusion Metadata Registry is primarily concerned with structural metadata so implements a subset of the SDMX RESTful API specification.

SDMX REST API Function Implemented
Structural Metadata Queries YES
Schema Queries (for retrieving SDMX-ML Structure Specific Data validation schemas) YES
Data Queries NO
Data Availability NO

The Fusion Metadata Registry API also provides some additional functions that are necessary for a practical registry implementation, but not explicitly provided for in SDMX standard REST specification.

FMR extended REST API Function Purpose
Structure Submission The addition or modification of structures using HTTP POST
Structure Deletion Delete specific structures using HTTP DELETE
Data Validation (synchronous) Validates a dataset submitted using HTTP POST returning a validation report in JSON
Data Transformation (synchronous) Transforms a dataset submitted using HTTP POST to a different DSD with an optional report returned in JSON
Data Transformation and Validation (asynchronous) Validates and transforms datasets asynchronously making it suitable for larger submissions
Product Info Returns details about the running Fusion Metadata Registry Instance in JSON
Active User Returns details about the current authenticated user in JSON

Structural Metadata Queries

A structural metadata query uses HTTP GET with the following general URL syntax: 

http(s)://ws-entry-point/resource/agencyID/resourceID/version

Resources

The following resources are defined:

  • datastructure (This has been shortened from DataStructureDefinition to allow for shorter URLs)
  • metadatastructure (This has been shortened from MetadataStructureDefinition to allow for shorter URLs)
  • categoryscheme
  • conceptscheme
  • codelist
  • hierarchicalcodelist
  • organisationscheme (The organisationscheme resource can be used whenever the role played by the organisation schemes is not known/relevant)
  • agencyscheme (For 3 of the subtypes of OrganisationScheme, the id and version parameters have fixed values. See Section 03 of the SDMX information model document for additional information)
  • dataproviderscheme
  • dataconsumerscheme
  • organisationunitscheme
  • dataflow
  • metadataflow
  • reportingtaxonomy
  • provisionagreement
  • structureset
  • process
  • categorisation
  • contentconstraint
  • actualconstraint (a type of contentconstraint stating what data are actually present)
  • allowedconstraint (a type of contentconstraint defining what data are allowed)
  • attachmentconstraint
  • transformationscheme
  • rulesetscheme
  • userdefinedoperatorscheme
  • customtypescheme
  • namepersonalisationscheme
  • vtlmappingscheme
  • structure (This type can be used to retrieve any type of structural metadata matching the supplied parameters)

Parameters

Parameters used for identifying a resource

The following parameters are used for identifying resources:

Parameter Type Description
agencyID A string compliant with the SDMX common:NCNameIDType The agency maintaining the artefact to be returned. It is possible to set more than one agency, using + as separator (e.g. BIS+ECB).
resourceID A string compliant with the SDMX common:IDType The id of the artefact to be returned. It is possible to set more than one id, using + as separator (e.g. CL_FREQ+CL_CONF_STATUS).
version A string compliant with the SDMX common:VersionType The version of the artefact to be returned. It is possible to set more than one version, using + as separator (e.g. 1.0+2.1).

The parameters mentioned above are specified using the following syntax: 

protocol://ws-entry-point/resource/agencyID/resourceID/version

Furthermore, some keywords may be used:

Keywords Scope Description
all agencyID Returns artefacts maintained by any maintenance agency
all resourceID Returns all resources of the type defined by the resource parameter
all version Returns all versions of the resource
latest version Returns the latest version in production of the resource

As all is a reserved keyword in the SDMX RESTful API, it is recommended not to use it as an identifier for agencies, resources or a specific version.

The following rules apply:

  • If no version is specified, the version currently used in production should be returned. It is therefore equivalent to using the keyword latest.
  • If no agencyID is specified, the matching artefacts maintained by any maintenance agency should be returned. It is therefore equivalent to using the keyword all. This would potentially return more than one artefact, if different agencies give the same identifier to a resource (for example, http://ws-entry-point/codelist/all/CL_FREQ, could return more than one codelist if more than one agency is maintaining a codelist with id "CL_FREQ").
  • If no resourceID is specified, all matching artefacts (according to the other criteria used) should be returned. It's is therefore equivalent to using the keyword all.
  • If no parameters are specified, the latest version of all resources of the type identified by the resource parameter, maintained by any maintenance agency should be returned.

Additional parameter used for identifying a resource, for item scheme types

SDMX uses the item scheme pattern to model SDMX collections of items. These are:

  • categoryscheme
  • conceptscheme
  • codelist
  • organisationscheme
  • agencyscheme
  • dataproviderscheme
  • dataconsumerscheme
  • organisationunitscheme
  • reportingtaxonomy
  • transformationscheme
  • rulesetscheme
  • userdefinedoperatorscheme
  • customtypescheme
  • namepersonalisationscheme
  • vtlmappingscheme

Although it is not following the item scheme pattern, hierarchicalcodelist is also a collection, i.e. a collection of hierarchies.

For these collections (those following the item scheme pattern or the hierarchicalcodelist), it is possible to use a 4th parameter for identifying a resource. The rules for the 3 other parameters, as defined in the section above, remain valid.

Parameter Type Description
itemID A string compliant with the SDMX common:NestedNCNameIDType for conceptscheme and agencyscheme, SDMX common:IDType for hierarchicalcodelist or with the SDMX common:NestedIDType in all other cases The id of the item to be returned. It is possible to set more than one id, using + as separator (e.g. A+Q+M).

This 4th parameter is used as follows: 

protocol://ws-entry-point/resource/agencyID/resourceID/version/itemID

Furthermore, a keyword may be used:

Keyword Scope Description
all itemID Returns all items belonging to the item scheme

The following rules apply:

  • If no itemID is specified, all the items belonging to the item scheme should be returned. It is therefore equivalent to using the keyword all.
  • If itemID is set and is a top-level id (e.g.: Code A (Annual) in the Frequency Codelist), and such an item exists in the matching item scheme, the item scheme returned should contain only the matching item and its isPartial parameter should be set to true.
  • If itemID is set and is a nested id (e.g.: Category A.1.1, belonging to Category A.1, belonging to Category A in a Category Scheme), and such an item exists in the matching item scheme, the item scheme returned should contain the matching item and its ancestors, and its isPartial parameter should be set to true.

Parameters used to further describe the desired results

The following parameters are used to further describe the desired results, once the resource has been identified. As mentioned in 3.2, these parameters appear in the query string part of the URL.

Parameter Type Description Default
detail String This attribute specifies the desired amount of information to be returned. For example, it is possible to instruct the web service to return only basic information about the maintainable artefact (i.e.: id, agency id, version and name). Most notably, items of item schemes will not be returned (for example, it will not return the codes in a code list query). Possible values are: allstubs (all artefacts should be returned as stubs, containing only identification information, as well as the artefacts' name), referencestubs (referenced artefacts should be returned as stubs, containing only identification information, as well as the artefacts' name), referencepartial (referenced item schemes should only include items used by the artefact to be returned. For example, a concept scheme would only contain the concepts used in a DSD, and its isPartial flag would be set to true. Likewise, if a dataflow has been constrained, then the codelists referenced by the DSD referenced by the dataflow should only contain the codes allowed by the content constraint), allcompletestubs (all artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information), referencecompletestubs (referenced artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information) and full (all available information for all artefacts should be returned). full
references String This attribute instructs the web service to return (or not) the artefacts referenced by the artefact to be returned (for example, the code lists and concepts used by the data structure definition matching the query), as well as the artefacts that use the matching artefact (for example, the dataflows that use the data structure definition matching the query). Possible values are: none (no references will be returned), parents (the artefacts that use the artefact matching the query), parentsandsiblings (the artefacts that use the artefact matching the query, as well as the artefacts referenced by these artefacts), children (artefacts referenced by the artefact to be returned), descendants (references of references, up to any level, will also be returned), all (the combination of parentsandsiblings and descendants). In addition, a concrete type of resource may also be used (for example, references=codelist). none

Applicability and meaning of references attribute

The table below lists the 1st level artefacts (one level up, one level down) that will be returned if the references parameter is set to all. Artefacts referenced by the matching artefact are displayed in regular style, while the artefacts that reference the matching artefact are displayed in Italic.

Maintainable artefact Artefacts returned
AgencyScheme Categorisation, Process, MetadataStructureDefinition, StructureSet
Categorisation All
CategoryScheme Categorisations, Process, StructureSet
Codelist Categorisation, Process, HierarchicalCodelist, ConceptScheme, DataStructureDefinition, MetadataStructureDefinition, StructureSet, VtlMappingScheme
ConceptScheme Categorisation, Process, Codelist, DataStructureDefinition, MetadataStructureDefinition, StructureSet, VtlMappingScheme
Constraint Categorisation, Process, DataProviderScheme, DataStructureDefinition, Dataflow, MetadataStructureDefinition, Metadataflow, ProvisionAgreement
DataConsumerScheme Categorisation, Process, MetadataStructureDefinition, StructureSet
Dataflow Categorisation, Process, Constraint, DataStructureDefinition, ProvisionAgreement, ReportingTaxonomy, StructureSet, VtlMappingScheme
DataProviderScheme Categorisation, Process, Constraint, ProvisionAgreement, MetadataStructureDefinition, StructureSet
DataStructureDefinition Categorisation, Process, Codelist, ConceptScheme, Constraint, Dataflow, StructureSet
HierarchicalCodelist Categorisation, Process, Codelist, StructureSet
Metadataflow Categorisation, Process, Constraint, MetadataStructureDefinition, ProvisionAgreement, ReportingTaxonomy, StructureSet
MetadataStructureDefinition Categorisation, Process, ConceptScheme, Codelist, DataProviderScheme, DataConsumerScheme, AgencyScheme, OrganisationUnitScheme, Constraint, Metadataflow, StructureSet
OrganisationUnitScheme Categorisation, Process, Constraint, MetadataStructureDefinition, StructureSet
Process All
ProvisionAgreement Categorisation, Process, DataProviderScheme, Dataflow, Metadataflow, Constraint
ReportingTaxonomy Categorisation, Process, Dataflow, Metadataflow, StructureSet
StructureSet Categorisation, Process, DataStructureDefinition, MetadataStructureDefinition, CategoryScheme, DataProviderScheme, DataConsumerScheme, AgencyScheme, OrganisationUnitScheme, ConceptScheme, Codelist, ReportingTaxonomy, HierarchicalCodelist, Dataflow, Metadataflow
CustomTypeScheme AgencyScheme, Categorisation, TranformationScheme
NamePersonalisationScheme AgencyScheme, Categorisation, TranformationScheme
RulesetScheme AgencyScheme, Categorisation, TranformationScheme, VtlMappingScheme
TranformationScheme AgencyScheme, Categorisation, CustomTypeScheme, NamePersonalisationScheme, RulesetScheme, UserDefinedOperatorScheme, VtlMappingScheme
UserDefinedOperatorScheme AgencyScheme, Categorisation, TranformationScheme, VtlMappingScheme
VtlMappingScheme AgencyScheme, Categorisation, Codelist, ConceptScheme, Dataflow, RulesetScheme, TranformationScheme, UserDefinedOperatorScheme

Examples

  • To retrieve version 1.0 of the DSD with id ECB_EXR1 maintained by the ECB, as well as the code lists and the concepts used in the DSD:

    http://ws-entry-point/datastructure/ECB/ECB_EXR1/1.0?references=children&detail=referencepartial

  • To retrieve the latest version in production of the DSD with id ECB_EXR1 maintained by the ECB, without the code lists and concepts of the DSD:

    http://ws-entry-point/datastructure/ECB/ECB_EXR1

  • To retrieve all DSDs maintained by the ECB, as well as the dataflows using these DSDs:

    http://ws-entry-point/datastructure/ECB?references=dataflow

  • To retrieve the latest version in production of all code lists maintained by all maintenance agencies, but without the codes:

    http://ws-entry-point/codelist?detail=allstubs

  • To retrieve, as stubs, the latest version in production of all maintainable artefacts maintained by the ECB:

    http://ws-entry-point/structure/ECB?detail=allstubs

  • To retrieve the category PRICES of the DOMAINS category scheme maintained by the ECB, as well as the categorisations referencing that category:

    http://ws-entry-point/categoryscheme/ECB/DOMAINS/latest/PRICES?references=categorisation

  • To retrieve the latest version of the CL_FREQ codelists maintained by the BIS or the ECB: http://ws-entry-point/codelist/BIS+ECB/CL_FREQ</p></li></ul>

    Schema queries

    Resources

    The following resource is defined:

    • schema

    This resource allows a client to ask a service to return a schema, i.e. a document which defines data validity within a certain context. The service must take into account the constraints that apply within that context (DSD or MSD, dataflow or metadataflow, or provision agreement).

    This is typically used for validation purposes but it may also be used for communication purposes, i.e. as a way to inform providers about the data they are expected to report.

    Parameters

    Parameters used for identifying a resource

    The following parameters are used for identifying resources:

    Parameter Type Description
    context One of the following: datastructure, metadatastructure, dataflow, metadataflow, provisionagreement The value of this parameter determines the constraints that need to be taken into account, when generating the schema. If datastructure or metadatastructure is used, constraints attached to the DSD or MSD must be applied when generating the schema. If dataflow or metadataflow is used, constraints attached to the dataflow or metadataflow and to the DSD or MSD used in the dataflow or metadataflow must be applied when generating the schema. If provisionagreement is used, constraints attached to the provision agreement, as well as to the dataflow or metadafalow used in the agreement and the DSD or MSD used in the dataflow or metadataflow must be applied when generating the schema.
    agencyID A string compliant with the SDMX common:NCNameIDType The agency maintaining the artefact used to generate the schema to be returned.
    resourceID A string compliant with the SDMX common:IDType The id of the artefact used to generate the schema to be returned.
    version A string compliant with the SDMX common:VersionType The version of the artefact used to generate the schema to be returned.

    The parameters mentioned above are specified using the following syntax: 

    protocol:// ws-entry-point/schema/context/agencyID/resourceID/version

    Furthermore, a keyword may be used:

    Keyword Scope Description
    latest version Returns the latest version in production of the resource

    As the query for schema must match one artefact only, the keyword all is not supported for agencyId and resourceId.

    The following rules apply:

    • If no version attribute is specified, the version currently used in production should be returned. It is therefore equivalent to using the keyword latest.

    Parameters used to further describe the desired results

    The following parameters are used to further describe the desired results, once the resource has been identified:

    Parameter Type Description
    dimensionAtObservation A string compliant with the SDMX common:NCNameIDType The ID of the dimension to be attached at the observation level.
    explicitMeasure Boolean For cross-sectional data validation, indicates whether observations are strongly typed (defaults to false).

    Using an SDMX format for the response

    By default, a schema query will return an XML schema (i.e. an xsd file). However, it is also possible to get the response in one of the SDMX Structure formats. In that case, the response should only include the following types of artefact: data structures, codelists, concept schemes and agency schemes. The various item schemes must only contain the following:

    • For codelists, the codes that are allowed after applying the constraints up to the specified context;
    • For concept schemes, the concepts that are used by the data structure;
    • For agency schemes, the agencies maintaining artefacts that are part of the response.

    Examples

    • To retrieve the schema for data supplied within the context of version 1.0 of the provision agreement EXR_WEB maintained by the ECB:

      http://ws-entry-point/schema/provisionagreement/ECB/EXR_WEB/1.0/

      In this case, the schema returned by the service must take into account the constraints attached to the provision agreement, the dataflow used in the provisionagreement and the data structure definition used in the dataflow.

    Structural Metadata Submission

    Structural metadata can be added or modified by using HTTP POST to submit any valid SDMX Structure Document to the secure API.

    Resource

    protocol://domain/ws/secure/sdmxapi/rest

    Example: https://registry.mydomain.org/FusionRegistry/ws/secure/sdmxapi/rest

    Authentication

    Only authenticated users with sufficient Agency or Admin privileges can modify structural metadata content. HTTP Basic Authentication must be used to with this service.

    Actions

    The following actions can be specified when submitting structural metadata content.

    Action Behaviour
    Append New maintainable structures are added, but an error occurs if any of the structures submitted already exist in the Registry
    Replace Existing maintainable structures are replaced in their entirety and new ones added if needed
    Merge Similar to Append except items are added to existing item schemes - useful for adding Codes to Codelists
    FullReplace The entire contents of the Registry are replaced with the structures submitted
    Delete The maintainables identified in the submitted content are deleted

    Submission Content Options

    The following SDMX Structure Documents can be submitted in the body of the POST:

    Message Type Action
    SDMX-ML Structure Message Specify the action using the HTTP 'Action' header (default is Replace)
    SDMX-JSON Structure Message Specify the action using the HTTP 'Action' header (default is Replace)
    SDMX-EDI (GESMES) Structure Message Specify the action using the HTTP 'Action' header (default is Replace)
    SDMX-ML SubmitStructureRequest Registry Interface Message Specify the action using the 'Action' header in the message

    The content can be Zipped, and multi-part submissions are also accepted.

    Response

    A successful submission results in a SDMX-ML SubmitStructureResponse message. If an error occurs, a SDMX-ML ErrorResponseDocument is returned.

    Structure Deletion

    The simplest way to delete Structural Metadata is using the HTTP DELETE verb.

    Resources

    Deletion of structures uses the same resources as Structural Metadata Queries to identify precisely what to delete.

    Maintainables 

    protocol://domain/ws/secure/sdmxapi/rest/resource/agencyID/resourceID/version

    Example:
    https://registry.mydomain.org/ws/secure/sdmxapi/rest/datastructure/ECB/ECB_TRD/1.0

    Items 

    protocol://domain/ws/secure/sdmxapi/rest/resource/agencyID/resourceID/version/itemID

    Examples:
    https://registry.mydomain.org/ws/secure/sdmxapi/rest/codelist/ECB/CL_FREQ/1.0/A
    https://registry.mydomain.org/ws/secure/sdmxapi/rest/codelist/ECB/CL_FREQ/1.0/A+M+Q

    Authentication

    Only authenticated users with sufficient Agency or Admin privileges can modify structural metadata content. HTTP Basic Authentication must be used to with this service.

    Response

    A successful submission results in a SDMX-ML SubmitStructureResponse message. If an error occurs, a SDMX-ML ErrorResponseDocument is returned.

Retrieved from "https://fmrwiki.sdmxcloud.org/index.php?title=REST_API_Overview&oldid=5710"