Merge pull request #191 from sdmx-twg/develop

Release version 2.1.0 of the REST API

api/sdmx-rest.yaml

@@ -1,11 +1,11 @@
 openapi: 3.0.0
 info:
- version: '2.0.0'
- title: 'SDMX RESTful API, v2.0.0'
+ version: '2.1.0'
+ title: 'SDMX RESTful API, v2.1.0'
  description: |
  The RESTful API for SDMX 3.0.
  
- For additional information, check the [documentation](https://github.com/sdmx-twg/sdmx-rest/tree/develop/v2_1/ws/rest/docs).
+ For additional information, check the [documentation](https://github.com/sdmx-twg/sdmx-rest/blob/master/doc/index.md).
 servers:
  - description: Mock implementation (just for demo purposes!)
  url: https://localhost/
@@ -122,7 +122,6 @@ paths:
  - $ref: '#/components/parameters/resourceID'
  - $ref: '#/components/parameters/version'
  - $ref: '#/components/parameters/dimensionAtObservation'
- - $ref: '#/components/parameters/explicitMeasure'
  - $ref: '#/components/parameters/accept-encoding'
  - $ref: '#/components/parameters/if-modified-since'
  responses:
@@ -240,6 +239,57 @@ paths:
  <<: *common_responses
  '200':
  $ref: '#/components/responses/200-meta'
+
+ /registration/id/{registrationID}:
+ get:
+ summary: 'Registration queries (by registration ID)'
+ tags: 
+ - Registration queries
+ description: |
+ These queries enable clients to request a data registration by its unique identifier
+ parameters:
+ - $ref: '#/components/parameters/resourceIDs'
+ responses:
+ <<: *common_responses
+ '200':
+ $ref: '#/components/responses/200-meta'
+
+ /registration/provider/{agencyID}/{providerID}:
+ get:
+ summary: 'Registration queries (by data provider ID)'
+ tags: 
+ - Registration queries
+ description: |
+ These queries enable clients to request data registrations by data provider(s)
+ parameters:
+ - $ref: '#/components/parameters/agencies'
+ - $ref: '#/components/parameters/resourceIDs'
+ - $ref: '#/components/parameters/updatedBeforeReg'
+ - $ref: '#/components/parameters/updatedAfterReg'
+ responses:
+ <<: *common_responses
+ '200':
+ $ref: '#/components/responses/200-meta'
+
+ /registration/{context}/{agencyID}/{resourceID}/{version}:
+ get:
+ summary: 'Registration queries (by context)'
+ tags: 
+ - Registration queries
+ description: |
+ These queries enable clients to request data registrations by data structure, dataflow, or provision agreement
+ parameters:
+ - $ref: '#/components/parameters/dataContext'
+ - $ref: '#/components/parameters/agencies'
+ - $ref: '#/components/parameters/resourceIDs'
+ - $ref: '#/components/parameters/versions'
+ - $ref: '#/components/parameters/updatedBeforeReg'
+ - $ref: '#/components/parameters/updatedAfterReg'
+ responses:
+ <<: *common_responses
+ '200':
+ $ref: '#/components/responses/200-meta' 
+
 components:
  parameters:
  dataContext:
@@ -278,7 +328,6 @@ components:
  dataflow,
  metadataflow,
  provisionagreement,
- structureset,
  process,
  categorisation,
  dataconstraint,
@@ -305,6 +354,9 @@ components:
  categoryschememap,
  organisationschememap,
  reportingtaxonomymap,
+ metadataproviderscheme,
+ reportingtaxonomy,
+ metadataprovisionagreement
  "*",
  ]
  itemSchemeType:
@@ -346,6 +398,7 @@ components:
  dataflow,
  metadataflow,
  provisionagreement,
+ metadataprovisionagreement,
  ]
  agencyID:
  in: path
@@ -395,7 +448,7 @@ components:
  in: path
  name: providerID
  description: | 
- The provider of metadata.
+ The provider of metadata or data.
 
  Multiple values are possible and `*` can be used as shortcut to select all available providers.
  required: true
@@ -435,7 +488,7 @@ components:
  type: array
  items:
  type: string
- pattern: '^(\*\+|~|\*|(0|[1-9]\d*[\+\*~]?|[\+\*~]?)\.(0|[1-9]\d*[\+\*~]?|[\+\*~]?)\.?(0|[1-9]\d*[\+\*~]?|[\+\*~]?)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?)$'
+ pattern: '^(\+|~(\.0){0,2}|\*(\.0){0,2}|(0|[1-9]\d*)(\.(0|[1-9]\d*))?|(0|[1-9]\d*)(\.(0|[1-9]\d*)){2}(-(([A-Za-z-][A-Za-z0-9-]*)|([A-Za-z0-9-]+[A-Za-z-][A-Za-z0-9-]*)|(0|[1-9][0-9]*))(\.(([A-Za-z-][A-Za-z0-9-]*)|([A-Za-z0-9-]+[A-Za-z-][A-Za-z0-9-]*)|(0|[1-9][0-9]*)))*)?|\+\.0\.0|[1-9]\d*(\.\+\.0|\+(\.(0|[1-9]\d*)){2}|\.(0|[1-9]\d*)(\.\+|\+\.(0|[1-9]\d*)|\.(0|[1-9]\d*)\+))|(0|[1-9]\d*)((\*|~)(\.(0|[1-9]\d*)){1,2}|\.(\*|~)(\.0)?|\.(0|[1-9]\d*)((\*|~)(\.(0|[1-9]\d*))?|\.(0|[1-9]\d*)?(\*|~)))(,(\+|~(\.0){0,2}|\*(\.0){0,2}|(0|[1-9]\d*)(\.(0|[1-9]\d*))?|(0|[1-9]\d*)(\.(0|[1-9]\d*)){2}(-(([A-Za-z-][A-Za-z0-9-]*)|([A-Za-z0-9-]+[A-Za-z-][A-Za-z0-9-]*)|(0|[1-9][0-9]*))(\.(([A-Za-z-][A-Za-z0-9-]*)|([A-Za-z0-9-]+[A-Za-z-][A-Za-z0-9-]*)|(0|[1-9][0-9]*)))*)?|\+\.0\.0|[1-9]\d*(\.\+\.0|\+(\.(0|[1-9]\d*)){2}|\.(0|[1-9]\d*)(\.\+|\+\.(0|[1-9]\d*)|\.(0|[1-9]\d*)\+))|(0|[1-9]\d*)((\*|~)(\.(0|[1-9]\d*)){1,2}|\.(\*|~)(\.0)?|\.(0|[1-9]\d*)((\*|~)(\.(0|[1-9]\d*))?|\.(0|[1-9]\d*)?(\*|~)))))*)$'
  style: simple
  items:
  in: path
@@ -565,14 +618,6 @@ components:
  schema:
  type: boolean
  default: false
- explicitMeasure:
- in: query
- name: explicitMeasure
- description: For cross-sectional data validation, indicates whether observations are strongly typed.
- required: false
- schema:
- type: boolean
- default: false
  structDetail:
  in: query
  name: detail
@@ -710,6 +755,24 @@ components:
  schema:
  type: string
  format: date-time
+ updatedBeforeReg:
+ in: query
+ name: updatedBefore
+ description: |
+ If this parameter is used, the returned message should only include data registrations updated before this period.
+ required: false
+ schema:
+ type: string
+ format: date-time 
+ updatedAfterReg:
+ in: query
+ name: updatedAfter
+ description: |
+ If this parameter is used, the returned message should only include data registrations updated after this period.
+ required: false
+ schema:
+ type: string
+ format: date-time
 
  responses:
  "200":

doc/availability.md

@@ -13,7 +13,7 @@ Parameter | Type | Description | Default | Multiple values?
 context | One of the following: `datastructure`, `dataflow`, `provisionagreement` | Data can be reported against a data structure, a dataflow or a provision agreement. This parameter allows selecting the desired context for data retrieval. | * | No
 agencyID | A string compliant with the SDMX *common:NCNameIDType* | The agency maintaining the artefact for which data have been reported. | * | Yes
 resourceID | A string compliant with the SDMX *common:IDType* | The id of the artefact for which data have been reported. | * | Yes
-version | A string compliant with the *VersionType* defined in the SDMX Open API specification | The version of the artefact for which data have been reported. | * | Yes
+version | A string compliant with the [SDMX *semantic versioning* rules](querying_versions.md) | The version of the artefact for which data have been reported. | * | Yes
 key | A string compliant with the *KeyType* defined in the SDMX Open API specification. | The combination of dimension values identifying the slice of the cube for which data should be returned. Wildcarding is supported via the `*` operator. For example, if the following key identifies the bilateral exchange rates for the daily US dollar exchange rate against the euro, D.USD.EUR.SP00.A, then the following key can be used to retrieve the data for all currencies against the euro: D.\*.EUR.SP00.A | * | Yes
 componentId | A string compliant with the SDMX common: IDType | The id of the Dimension for which to obtain availability information about. In the case where this information is not provided, data availability will be provided for all Dimensions. | * | Yes
 c | Map | Filter data by component value. For example, if a structure defines a frequency dimension (FREQ) and the code A (Annual) is an allowed value for that dimension, the following can be used to retrieve annual data: `c[FREQ]=A`. The same applies to attributes (e.g. `c[CONF_STATUS]=F`) and measures. Multiple values are supported, using a comma (`,`) as separator: `c[FREQ]=A,M`. In case of attributes that support multiple values, the plus (`+`) can be used to list all values that an attribute must have. For example, to indicate that ATTR1 must either be A or (B AND M), use the following: `c[ATTR1]=A,B+M`. Operators may be used too (see table with operators below). This parameter can be used in addition, or instead of, the `key` path parameter. This parameter may be used multiple times (e.g. `c[FREQ]=A,M&c[CONF_STATUS]=F`) | | Yes
@@ -138,11 +138,11 @@ The following media types can be used with _availability_ queries:
 
 - **application/vnd.sdmx.structure+json;version=2.0.0**
 - application/vnd.sdmx.structure+xml;version=3.0.0
-- application/vnd.sdmx.structure+xml;version=2.1
-- application/vnd.sdmx.structure+json;version=1.0.0
 
 The default format is highlighted in **bold**.
 
+For media types of previous SDMX versions, please consult the documentation of the SDMX version you are interested in.
+
 ## Examples
 
 - To retrieve the distinct values for each Dimension for the entire ECB_EXR1_WEB dataflow. The metadata used to decode the code ids and concept ids into human readable labels is also requested.

doc/content_negotiation.md

@@ -2,6 +2,9 @@
 
 [HTTP Content Negotiation](https://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html) is a mechanism offered by HTTP that allows clients to indicate their preferred representation, language, encoding, etc. for a resource.
 
+> [!TIP]
+> HTTP Content-Negotiation is the standard way to support features such as format or language selection. However, there are use cases where an alternative is required. Please check the [Extending the SDMX REST API](extend.md) section for additional information about the alternative way of supporting these features. 
+
 ## Format selection
 
 Using the HTTP Content Negotiation mechanism, the client specifies the desired format for the resource using the [Accept header](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).
@@ -24,6 +27,20 @@ The full list of media types is available in the _Response types_ section of the
 - [Schema queries](schema.md#response-types)
 - [Data availability queries](availability.md#response-types)
 
+## Selection of the appropriate version
+
+Usually, clients will indicate the precise version of the format they support (for example, version 2.0.0 of SDMX-JSON). 
+
+However, clients may also use semantic versioning, to indicate that they are capable of handling any version matching the supplied semantic versioning string (e.g. `2.3+.1`).
+
+Examples:
+
+- application/vnd.sdmx.structure+xml;version=3.0.0+
+- application/vnd.sdmx.data+json;version=2.3+.1
+- application/vnd.sdmx.data+csv;version=2+.0.1
+
+For additional information about semantic versioning in SDMX, please refer to [Section 06 (Technical Notes)](https://sdmx.org/wp-content/uploads/SDMX_3-0-0_SECTION_6_FINAL-1_0.pdf) of the SDMX 3.0 Documentation package.
+
 ## Selection of the appropriate language
 
 The [Accept-Language header](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) is used to indicate the language preferences of the client. Multiple values, along with their respective weights, are possible. For example: