Merge pull request #47 from sdmx-twg/v1.2.0

Merged v1.2.0 into Master
sdmx-twg · May 2, 2017 · 672226a · 672226a
2 parents c9d9b4a + b51a2ac
commit 672226a
Show file tree

Hide file tree

Showing 7 changed files with 40 additions and 11 deletions.
diff --git a/v2_1/ws/rest/docs/4_3_structural_queries.md b/v2_1/ws/rest/docs/4_3_structural_queries.md
@@ -64,7 +64,7 @@ The following rules apply:
 
 #### 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:
+SDMX uses the *item scheme* pattern to model SDMX collections of items. These are:
 
 - categoryscheme
 - conceptscheme
@@ -76,11 +76,13 @@ SDMX uses the item scheme pattern to model SDMX collections of items. These are:
 - organisationunitscheme
 - reportingtaxonomy
 
-For these collections, 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.
+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, or with the SDMX *common:NestedIDType* in all other cases | The id of the item to be returned.
+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.
 
 
 This 4th parameter is used as follows:

diff --git a/v2_1/ws/rest/docs/4_6_conneg.md b/v2_1/ws/rest/docs/4_6_conneg.md
@@ -1,8 +1,12 @@
-## Selection of the Appropriate Representation
+## HTTP Content-Negotiation
 
-Selection of the appropriate formats for the response message is made using the mechanisms defined for [HTTP Content Negotiation](https://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html). Using the HTTP Content Negotiation mechanism, the client specifies the desired format and version of the resource using the [Accept HTTP header](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).
+[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.
 
-Along with official mime types (e.g.: text/html, application/xml, etc), the standard also defines a syntax allowing a service to define its own types. The SDMX Restful API makes use of this functionality and the syntax is as follows:
+### Selection of the Appropriate Representation
+
+Using the HTTP Content Negotiation mechanism, the client specifies the desired format and version of the resource using the [Accept header](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).
+
+Along with official mime types (e.g.: text/html, application/xml, etc), the HTTP standard also defines a syntax, which the SDMX RESTful API leverages, allowing a service to define its own types:
 
  application/vnd.sdmx.[format]+xml;version=[version]
 
@@ -30,3 +34,21 @@ The list below indicates the valid formats for SDMX RESTful web services, compli
  application/vnd.sdmx.structurespecificmetadata+xml;version=2.1
  application/vnd.sdmx.structure+xml;version=2.1
  application/vnd.sdmx.schema+xml;version=2.1
+
+### 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:
+
+```
+Accept-Language: ru, en-gb;q=0.8, en;q=0.7
+```
+
+### Enabling data compression
+
+Compression could be enabled using the appropriate [Accept-Encoding header](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).
+
+### Helping web caches and Content Delivery Networks (CDN)
+
+The [Vary header](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) is used to indicate the list of headers that are relevant for a particular service.
+
+For example, services that offer data in multiple formats will rely on the HTTP Accept header, but this header will likely be irrelevant for services that support only one format. Using the `Vary` header to indicate which headers are effectively used by the server helps web caches and Content Delivery Networks to build appropriate cache keys.
diff --git a/v2_1/ws/rest/docs/4_7_compression.md b/v2_1/ws/rest/docs/4_7_compression.md
diff --git a/v2_1/ws/rest/docs/4_8_errors.md → v2_1/ws/rest/docs/4_7_errors.md b/v2_1/ws/rest/docs/4_8_errors.md → v2_1/ws/rest/docs/4_7_errors.md
@@ -1,4 +1,4 @@
-## Error handling
+## Error handling and status information
 
 RESTful web services should indicate errors using the proper HTTP status code. In addition, whenever appropriate, the error should also be returned using the error message offered starting with version 2.1 of SDMX-ML.
 
@@ -66,3 +66,10 @@ SDMX error | HTTP status code
 503 Service unavailable | 503 Service unavailable
 510 Response size exceeds service limit | 413 Request entity too large
 1000+ | 500 Internal server error
+
+### Other useful HTTP status codes
+
+Apart from the error codes mentioned above, there are a few additional [HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) that are typically encountered when consuming a SDMX RESTful web service. These are:
+
+- `200`: This is the standard response for successful HTTP requests. With `GET` requests, it is used to indicate that the request was successfully processed and that the data are available in the body of the response.
+- `304`: This is used to indicate that there are no changes since the version specified by the request headers `If-Modified-Since` or `If-None-Match`. The response does not include matching data, as the client can still use the previously-downloaded copy.
diff --git a/v2_1/ws/rest/docs/rest_cheat_sheet.odt b/v2_1/ws/rest/docs/rest_cheat_sheet.odt
diff --git a/v2_1/ws/rest/docs/rest_cheat_sheet.pdf b/v2_1/ws/rest/docs/rest_cheat_sheet.pdf
diff --git a/v2_1/ws/rest/src/sdmx-rest.wadl b/v2_1/ws/rest/src/sdmx-rest.wadl
@@ -57,10 +57,11 @@
  </response>
  </method>
  </resource>
- <resource id="hierarchicalcodelist" path="hierarchicalcodelist/{agencyID}/{resourceID}/{version}"> 
+ <resource id="hierarchicalcodelist" path="hierarchicalcodelist/{agencyID}/{resourceID}/{version}/{itemID}"> 
  <param name="agencyID" type="types:NestedNCNameIDType" style="template" required="false" default="all"/> 
  <param name="resourceID" type="types:IDType" style="template" required="false" default="all"/> 
  <param name="version" type="types:VersionType" style="template" required="false" default="latest"/>
+ <param name="itemID" type="types:IDType" style="template" required="false" default="all"/>
  <method name="GET" id="HierarchicalCodelistQuery"> 
  <request> 
  <param name="detail" type="types:DetailType" style="query" default="full"/>