Difference between revisions of "Reference Metadata API"

From Fusion Registry Wiki
Jump to navigation Jump to search
(Created page with "Category:WebService")
 
(→‎Examples)
 
(20 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
[[Category:WebService]]
 
[[Category:WebService]]
 +
[[Category:Reference_Metadata]]
 +
 +
See [[Reference_Metadata|Reference Metadata]]
 +
 +
= Overview =
 +
This API supports GET (retrieve reference metadata), POST (submit new or modified reports), and DELETE (remove existing reports) methods to maintain Reference Metadata Reports. 
 +
 +
The GET methods conform to the [https://github.com/sdmx-twg/sdmx-rest/blob/master/doc/metadata.md SDMX REST Specification for reference metadata retrieval].
 +
 +
== GET Reference Metadata ==
 +
{| class="wikitable"
 +
|-
 +
|style="background-color:#eaecf0"|<b>Entry Point</b>|| <b> /sdmx/v2/metadata</b>
 +
|-
 +
|style="background-color:#eaecf0"|<b>Access</b>|| <span style='color:green'><b>Public</b></span>
 +
|-
 +
|style="background-color:#eaecf0"|<b>Http Method</b>|| GET
 +
|-
 +
|style="background-color:#eaecf0"|<b>Response Format</b>|| JSON
 +
|-
 +
|style="background-color:#eaecf0"|<b>Response Statuses</b>|| <p><b>200</b> - Success</p>
 +
<p><b>401</b> - Unauthorized (if access has been restricted)</p>
 +
<p><b>500</b> - Server Error</p>
 +
|}
 +
 +
[https://github.com/sdmx-twg/sdmx-rest/blob/master/doc/metadata.md See Specification].
 +
 +
==Examples==
 +
Get specific report
 +
https://example.registry.com/sdmx/v2/metadata/metadataset/MT/REPORT1/1.0
 +
 +
Get all metadata sets for a specific Metadata Provider
 +
https://example.registry.com/sdmx/v2/metadata/metadataset/MT.PROVIDER/*/*
 +
 +
Get all reports against Metadataflow as Stubs (only include basic details, not the actual reported content)
 +
https://example.registry.com/sdmx/v2/metadata/metadataflow/MT/MDF1/1.0?detail=allStubs
 +
 +
Get  all reports against Metadataflow for a specific Metadata Provider
 +
https://example.registry.com/sdmx/v2/metadata/metadataflow/MT/MDF1/1.0/PROVIDER1
 +
 +
Get all reports against any BIS Codelist
 +
https://example.registry.com/sdmx/v2/metadata/structure/codelist/BIS
 +
 +
== POST Reference Metadata ==
 +
{| class="wikitable"
 +
|-
 +
|style="background-color:#eaecf0"|<b>Entry Point</b>|| <b> /ws/secure/sdmx/v2/metadata</b>
 +
|-
 +
|style="background-color:#eaecf0"|<b>Access</b>|| <span style='color:red'><b>Secure</b></span>
 +
|-
 +
|style="background-color:#eaecf0"|<b>Http Method</b>|| POST
 +
|-
 +
|style="background-color:#eaecf0"|<b>Accepts</b>|| [https://github.com/sdmx-twg/sdmx-json/tree/master/metadata-message SDMX-JSON]
 +
|-
 +
|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>
 +
<p>2. application/text or application/json (if submitting data in the body of the POST)</p>
 +
|-
 +
|style="background-color:#eaecf0"|<b>Response Format</b>|| N/A
 +
|-
 +
|style="background-color:#eaecf0"|<b>Response Statuses</b>|| <p><b>200</b> - Success</p>
 +
<p><b>401</b> - Unauthorized (if access has been restricted)</p>
 +
<p><b>500</b> - Server Error</p>
 +
|}
 +
 +
Submit a Reference Metadata report, on success an HTTP 200 status is returned.  On failure an SDMX Error message is returned with the HTTP status code set to the appropriate code. 
 +
 +
Example Error:
 +
 +
<?xml version="1.0" ?>
 +
<message:Error xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:message="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message" xmlns:com="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/common">
 +
  <message:ErrorMessage code="100">
 +
    <com:Text>Could not resolve reference from structure Metadata Set 'MT:EXAMPLE1.0.0)' to structure Metadata Provision Agreement 'MT:MUK1_EXAMPLE(1.0)'</com:Text>
 +
  </message:ErrorMessage>
 +
</message:Error>
 +
 +
== DELETE Reference Metadata ==
 +
{| class="wikitable"
 +
|-
 +
|style="background-color:#eaecf0"|<b>Entry Point</b>|| <b> /ws/secure/sdmx/v2/metadata</b>
 +
|-
 +
|style="background-color:#eaecf0"|<b>Access</b>|| <span style='color:red'><b>Secure</b></span>
 +
|-
 +
|style="background-color:#eaecf0"|<b>Http Method</b>|| DELETE
 +
|-
 +
|style="background-color:#eaecf0"|<b>Response Format</b>||
 +
|-
 +
|style="background-color:#eaecf0"|<b>Response Statuses</b>|| <p><b>200</b> - Success</p>
 +
<p><b>401</b> - Unauthorized (if access has been restricted)</p>
 +
<p><b>500</b> - Server Error</p>
 +
|}
 +
 +
Deletes all reference metadata reports which match the query URL, the path parameters following the /metadata/ are used to create a filter on the Metadata Reports.  The path uses the same syntax as the
 +
[https://github.com/sdmx-twg/sdmx-rest/blob/master/doc/metadata.md GET parameters], it is therefore possible to delete by specific report identifiers, by metadataflow, or by structure query.
 +
 +
==Examples==
 +
Delete specific report
 +
https://example.registry.com/ws/secure/sdmx/v2/metadata/metadataset/MT/REPORT1/1.0
 +
 +
Delete all versions of report
 +
https://example.registry.com/ws/secure/sdmx/v2/metadata/metadataset/MT/REPORT1/*
 +
 +
Delete all reports against Metadataflow
 +
https://example.registry.com/ws/secure/sdmx/v2/metadata/metadataflow/MT/MDF1/1.0
 +
 +
Delete all reports against Metadataflow for a specific Metadata Provider
 +
https://example.registry.com/ws/secure/sdmx/v2/metadata/metadataflow/MT/MDF1/1.0/PROVIDER1
 +
 +
Delete all reports against all BIS Codelists
 +
https://example.registry.com/ws/secure/sdmx/v2/metadata/strucure/codelist/BIS

Latest revision as of 00:04, 9 April 2024


See Reference Metadata

Overview

This API supports GET (retrieve reference metadata), POST (submit new or modified reports), and DELETE (remove existing reports) methods to maintain Reference Metadata Reports.

The GET methods conform to the SDMX REST Specification for reference metadata retrieval.

GET Reference Metadata

Entry Point /sdmx/v2/metadata
Access Public
Http Method GET
Response Format JSON
Response Statuses

200 - Success

401 - Unauthorized (if access has been restricted)

500 - Server Error

See Specification.

Examples

Get specific report 

https://example.registry.com/sdmx/v2/metadata/metadataset/MT/REPORT1/1.0

Get all metadata sets for a specific Metadata Provider 

https://example.registry.com/sdmx/v2/metadata/metadataset/MT.PROVIDER/*/*

Get all reports against Metadataflow as Stubs (only include basic details, not the actual reported content) 

https://example.registry.com/sdmx/v2/metadata/metadataflow/MT/MDF1/1.0?detail=allStubs

Get all reports against Metadataflow for a specific Metadata Provider 

https://example.registry.com/sdmx/v2/metadata/metadataflow/MT/MDF1/1.0/PROVIDER1

Get all reports against any BIS Codelist 

https://example.registry.com/sdmx/v2/metadata/structure/codelist/BIS

POST Reference Metadata

Entry Point /ws/secure/sdmx/v2/metadata
Access Secure
Http Method POST
Accepts SDMX-JSON
Content-Type

1. multipart/form-data (if attaching file) – the attached file must be in field name of uploadFile

2. application/text or application/json (if submitting data in the body of the POST)

Response Format N/A
Response Statuses

200 - Success

401 - Unauthorized (if access has been restricted)

500 - Server Error

Submit a Reference Metadata report, on success an HTTP 200 status is returned. On failure an SDMX Error message is returned with the HTTP status code set to the appropriate code.

Example Error: 

<?xml version="1.0" ?>
<message:Error xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:message="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message" xmlns:com="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/common">
 <message:ErrorMessage code="100">
   <com:Text>Could not resolve reference from structure Metadata Set 'MT:EXAMPLE1.0.0)' to structure Metadata Provision Agreement 'MT:MUK1_EXAMPLE(1.0)'</com:Text>
 </message:ErrorMessage>
</message:Error>

DELETE Reference Metadata

Entry Point /ws/secure/sdmx/v2/metadata
Access Secure
Http Method DELETE
Response Format
Response Statuses

200 - Success

401 - Unauthorized (if access has been restricted)

500 - Server Error

Deletes all reference metadata reports which match the query URL, the path parameters following the /metadata/ are used to create a filter on the Metadata Reports. The path uses the same syntax as the GET parameters, it is therefore possible to delete by specific report identifiers, by metadataflow, or by structure query.

Examples

Delete specific report 

https://example.registry.com/ws/secure/sdmx/v2/metadata/metadataset/MT/REPORT1/1.0

Delete all versions of report 

https://example.registry.com/ws/secure/sdmx/v2/metadata/metadataset/MT/REPORT1/*

Delete all reports against Metadataflow 

https://example.registry.com/ws/secure/sdmx/v2/metadata/metadataflow/MT/MDF1/1.0

Delete all reports against Metadataflow for a specific Metadata Provider 

https://example.registry.com/ws/secure/sdmx/v2/metadata/metadataflow/MT/MDF1/1.0/PROVIDER1

Delete all reports against all BIS Codelists 

https://example.registry.com/ws/secure/sdmx/v2/metadata/strucure/codelist/BIS
Retrieved from "https://wiki.sdmxcloud.org/index.php?title=Reference_Metadata_API&oldid=6711"