REST API Overview

From FMR Knowledge Base
Revision as of 05:35, 20 January 2021 by Glenn (talk | contribs) (→‎Parameters used for identifying a resource)
Jump to navigation Jump to search


Scope of the 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.

Structural Metadata Queries

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

Data and Metadata Queries

Resources

The following resources should be supported:

  • data
  • metadata

Parameters

Parameters used for identifying a resource

The following parameters are used for identifying resources in data queries:

Parameter Type Description
flowRef A string identifying the dataflow. The syntax is agency id, artefact id, version, separated by a ",". For example: AGENCY_ID,FLOW_ID,VERSION. In case the string only contains one out of these 3 elements, it is considered to be the flow id, i.e. all,FLOW_ID,latest. In case the string only contains two out of these 3 elements, they are considered to be the agency id and the flow id, i.e. AGENCY_ID,FLOW_ID,latest. The data (or metadata) flow of the data (or metadata) to be returned. Its a common use case in SDMX-based web services that the flow id is sufficient to uniquely identify a dataflow. Should this not be the case, the agency id and the dataflow version, can be used, in conjunction with the flow id, in order to uniquely identify a dataflow.
key A string compliant with the KeyType defined in the SDMX WADL. The key of the artefact to be returned. Wildcarding is supported by omitting the dimension code for the dimension to be wildcarded. For example, if the following series key identifies the bilateral exchange rates for the daily US dollar exchange rate against the euro, D.USD.EUR.SP00.A, then the following series key can be used to retrieve the data for all currencies against the euro: D..EUR.SP00.A.The OR operator is supported using the + character. For example, the following series key can be used to retrieve the exchange rates against the euro for both the US dollar and the Japanese Yen: D.USD+JPY.EUR.SP00.A.
providerRef A string identifying the provider. The syntax is agency id, provider id, separated by a ",". For example: AGENCY_ID,PROVIDER_ID. In case the string only contains one out of these 2 elements, it is considered to be the provider id, i.e. all,PROVIDER_ID. The provider of the data (or metadata) to be retrieved. If not supplied, the returned message will contain data (or metadata) provided by any provider. Its a common use case in SDMX-based web services that the provider id is sufficient to uniquely identify a data provider. Should this not be the case, the agency can be used, in conjunction with the provider id, in order to uniquely identify a data provider. The OR operator is supported using the + character. For example, the following value can be used to indicate that the data should be provided by the Swiss National Bank (CH2) or Central Bank of Norway (NO2): CH2+NO2.

The parameters mentioned above are specified using the following syntax: 

protocol://ws-entry-point/resource/flowRef/key/providerRef

Furthermore, some keywords may be used:

Keywords Scope Description
all key Returns all data belonging to the specified dataflow and provided by the specified provider.
all providerRef Returns all data matching the supplied key and belonging to the specified dataflow that has been provided by any data provider. As all is a reserved keyword in the SDMX RESTful API, it is recommended not to use it as an identifier for providers.

The following rules apply:

  • If no key is specified, all data (or metadata) belonging to the dataflow (or metadataflow) identified by the flowRef should be supplied. It is therefore equivalent to using the keyword all.
  • If no providerRef is specified, the matching data (or metadata) provided by any data provider should be returned. It is therefore equivalent to using the keyword all.

Parameters used to further filter the desired results

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


Fusion Metadata Registry Extended API

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