Difference between revisions of "Transaction Web Service"

From Fusion Registry Wiki
Jump to navigation Jump to search
(Created page with "= Overview = The Transaction Web Service provides access to all the structural metadata content of the Fusion Registry (including any content that has been subsequently delet...")
 
 
(41 intermediate revisions by one other user not shown)
Line 1: Line 1:
 +
[[Category:WebService]]
 
= Overview =
 
= Overview =
  
 
The Transaction Web Service provides access to all the structural metadata content of the Fusion Registry (including any content that has been subsequently deleted). A Transaction is the submission of a structure, group of structures or data registration.  
 
The Transaction Web Service provides access to all the structural metadata content of the Fusion Registry (including any content that has been subsequently deleted). A Transaction is the submission of a structure, group of structures or data registration.  
  
 +
= Querying and Searching All Transactions =
 +
 +
Returns a JSON Array of all of the structures in the Registry, filterable by parameter.
 +
 +
{| class="wikitable"
 +
|-
 +
|style="background-color:#eaecf0"|<b>Entry Point</b> || style="min-width:500px;" | <b> /ws/registry/tx/searchTransactions</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> || application/json
 +
|-
 +
|style="background-color:#eaecf0"|<b>Response Statuses</b> || <p><b>200</b> - Submission Accepted</p>
 +
|}
 +
 +
=== Response ===
 +
The output shows the Date (as a millisecond epoch time), the Transaction Id, the action and the Transaction Type. A typical example:
 +
  [
 +
    {
 +
      "Date": 1612434466642,
 +
      "Id": 785,
 +
      "Action": "Replace",
 +
      "Type": "Structure Submission"
 +
    },
 +
    {
 +
      "Date": 1612434448408,
 +
      "Id": 784,
 +
      "Action": "Replace",
 +
      "Type": "Structure Submission"
 +
    },
 +
    ...
 +
  ]
 +
 +
 +
=== HTTP Query Parameters ===
 +
If no parameters are supplied all transactions known to the Registry will be returned. If any of the filters applied below result in no results, an empty JSON response (HTTP 200) is returned.
 +
 +
{| class="wikitable"
 +
|-
 +
!| Request Parameter || Required || Purpose
 +
|-
 +
|style="background-color:#eaecf0"|<b>action</b> || No || Filters the response to only include Transaction for the specified action. Legal values are Append, Replace, FullReplace and Delete.
 +
|-
 +
|style="background-color:#eaecf0"|<b>dateFrom</b> || No || Filters the response to only include Transactions from the specified time. The value must be specified as the epoch time in milliseconds (e.g. 1609459200000 is the start of the year 2021).
 +
|-
 +
|style="background-color:#eaecf0"|<b>dateTo</b> || No || Filters the response to only include Transactions up to the specified time. The value must be specified as the epoch time in milliseconds (e.g. 1609459200000 is the start of the year 2021).
 +
|-
 +
|style="background-color:#eaecf0"|<b>max</b> || No || Limits the returned response to only containing at most the specified value.
 +
|-
 +
|style="background-color:#eaecf0"|<b>orderDesc</b> || No || The default output is that Transactions are returned in a descending order (most recent first). Supplying ''false'' to this parameter reverses the order.
 +
|-
 +
|style="background-color:#eaecf0"|<b>user</b> || No || Filters the response to only include Transactions for the specified user.
 +
|}
 +
 +
= Querying for all URNs =
 +
 +
Returns a JSON Array of all the maintainable URNs (both current and deleted) in the Registry.
 +
 +
{| class="wikitable"
 +
|-
 +
|style="background-color:#eaecf0"|<b>Entry Point</b> || style="min-width:500px;" | <b>/ws/registry/tx/getAllUrns</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> || application/json
 +
|-
 +
|style="background-color:#eaecf0"|<b>Response Statuses</b> || <p><b>200</b> - Submission Accepted</p>
 +
|}
 +
 +
=== Response ===
 +
An alphabetically ordered list of all of the URNs in the system. A typical example:
 +
  [
 +
    "urn:sdmx:org.sdmx.infomodel.codelist.Codelist=SDMX:CL_BAR(1.0)",
 +
    "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=AAA.SUB1:DF1(1.0)",
 +
    "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=WB:WDI_POVERTY(1.0)",
 +
    "urn:sdmx:org.sdmx.infomodel.registry.ProvisionAgreement=BIS.LBS:TLBR_WS8_BIS_PH2(1.0)",
 +
    ...
 +
  ]
 +
 +
= Querying for a specific URN =
 +
Provides information regarding who made changes to a particular structure. It returns the user id (and date, transaction id and action) of who last modified the maintainable with the given URN.
 +
 +
{| class="wikitable"
 +
|-
 +
|style="background-color:#eaecf0"|<b>Entry Point</b> || style="min-width:500px;" | <b>/ws/registry/tx/history</b>
 +
|-
 +
|style="background-color:#eaecf0"|<b>Access</b> || <span style='color:green'><b>Public</b></span>  '''Note:''' More information is provided if authenticated
 +
|-
 +
|style="background-color:#eaecf0"|<b>Http Method</b> || GET
 +
|-
 +
|style="background-color:#eaecf0"|<b>Response Format</b> || application/json
 +
|-
 +
|style="background-color:#eaecf0"|<b>Response Statuses</b> || <p><b>200</b> - Submission Accepted</p> <p><b>400</b> - Illegal URN</p>
 +
|}
 +
 +
=== Response ===
 +
An ordered list of transactions (lowest transaction number first) of the transactions for the specified URN, showing the date, transaction ID and Action. A typical example:
 +
 +
  [
 +
    {
 +
      "Date": 1612358238673,
 +
      "Id": 449,
 +
      "Action": "Replace",
 +
      "Type": "Structure Submission"
 +
    },
 +
    {
 +
      "Date": 1612358239170,
 +
      "Id": 450,
 +
      "Action": "Delete",
 +
      "Type": "Structure Submission"
 +
    },
 +
    {
 +
      "Date": 1612358239657,
 +
      "Id": 451,
 +
      "Action": "Replace",
 +
      "Type": "Structure Submission"
 +
    },
 +
    ...
 +
  ]
 +
 +
If the query is provided with correct authentication credentials of an administrator then the User ID of the user who performed the change is also returned. An example of this:
 +
 +
  [
 +
    {
 +
      "Date": 1612358238673,
 +
      "Id": 449,
 +
      <span style='color:green'>"User": "admin1",</span>
 +
      "Action": "Replace",
 +
      "Type": "Structure Submission"
 +
    },
 +
 +
=== HTTP Query Parameters ===
 +
{| class="wikitable"
 +
|-
 +
!| Request Parameter || Required || Purpose
 +
|-
 +
|style="background-color:#eaecf0"|<b>urn</b> || Yes || The URN of the requested structure.
 +
|}
 +
 +
= Querying for a specific Transaction =
 +
For a specific Transaction ID, all of the structures can be requested for that Transaction.
 +
 +
{| class="wikitable"
 +
|-
 +
|style="background-color:#eaecf0"|<b>Entry Point</b> || style="min-width:500px;" | <b>/ws/registry/tx/transactions</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> || application/json SDMX
 +
|-
 +
|style="background-color:#eaecf0"|<b>Response Statuses</b> || <p><b>200</b> - Submission Accepted</p>
 +
|}
 +
 +
=== Response ===
 +
The output will be in the format requested, showing all of the structures for the specific transaction. An example showing SDMX-ML 2.1 for a Dataflow:
 +
 +
  <?xml version="1.0" encoding="UTF-8"?>
 +
  <mes:RegistryInterface xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xml="http://www.w3.org/XML/1998/namespace" xmlns:mes="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message" xmlns:str="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/structure" xmlns:com="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/common" xsi:schemaLocation="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message https://registry.sdmx.org/schemas/v2_1/SDMXMessage.xsd">
 +
    <mes:Header>
 +
      <mes:ID>IREF422205</mes:ID>
 +
      <mes:Test>false</mes:Test>
 +
      <mes:Prepared>2021-02-04T12:37:05Z</mes:Prepared>
 +
      <mes:Sender id="REGISTRY1"/>
 +
      <mes:Receiver id="not_supplied"/>
 +
    </mes:Header>
 +
    <mes:SubmitStructureRequest action="Information">
 +
      <str:Structures>
 +
        <str:Dataflows>
 +
          <str:Dataflow urn="urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=ESTAT:HC02(2.0)" isExternalReference="false" agencyID="ESTAT" id="HC02" isFinal="false" version="2.0">
 +
            <com:Name xml:lang="en">HC02 - Population by Household Status and Educational Attainment</com:Name>
 +
            <str:Structure>
 +
              <Ref package="datastructure" agencyID="ESTAT" id="HC02" version="1.0" class="DataStructure"/>
 +
            </str:Structure>
 +
          </str:Dataflow>
 +
        </str:Dataflows>
 +
      </str:Structures>
 +
    </mes:SubmitStructureRequest>
 +
  </mes:RegistryInterface>
 +
 +
=== HTTP Query Parameters ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Entry Point</b>|| <b> /ws/registry/tx/searchTransactions</b>
+
!| Request Parameter || Required || Purpose
 +
|-
 +
|style="background-color:#eaecf0"|<b>urn</b> || Yes || The URN of the requested structure.
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Access</b>|| <span style='color:red'><b>Secure</b></span> Public
+
|style="background-color:#eaecf0"|<b>format</b> || No || A structure format. Default output is SDMX-ML 2.1. Other options include sdmx-json, fusion-json, sdmx-edi.
 +
|}
 +
 
 +
= Last User to Edit a Structure=
 +
Returns only the user id of the last user to edit a specific structure.
 +
 
 +
{| class="wikitable"
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Http Method</b>|| GET
+
|style="background-color:#eaecf0"|<b>Entry Point</b> || style="min-width:500px;" | <b>/ws/registry/tx/userIdFromReg</b>
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Accepts</b>|| CSV, XLSX, SDMX-ML, SDMX-EDI (any format for which there is a Data Reader)
+
|style="background-color:#eaecf0"|<b>Access</b> || <span style='color:green'><b>Public</b></span>
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Compression</b> || Zip files supported, if loading from URL gzip responses supported
+
|style="background-color:#eaecf0"|<b>Http Method</b> || GET
 
|-
 
|-
−
|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>
+
|style="background-color:#eaecf0"|<b>Response Format</b> || application/json
−
<p>2. application/text or application/xml (if submitting data in the body of the POST)</p>
+
|}
 +
 
 +
=== Response ===
 +
An example output
 +
  {"userId":"admin1"}
 +
 
 +
=== HTTP Query Parameters ===
 +
{| class="wikitable"
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Response Format</b>|| Determined by [[Data Formats|Accept Header]] - default SDMX 2.1 Structure Specific
+
!| Request Parameter || Required || Purpose
 
|-
 
|-
−
|style="background-color:#eaecf0"|<b>Response Statuses</b>|| <p><b>200</b> - Submisson Accepted</p>
+
|style="background-color:#eaecf0"|<b>urn</b> || Yes || The URN of the requested structure.
−
<p><b>400</b> - Submission 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>
 
 
|}
 
|}

Latest revision as of 08:54, 2 August 2023

Overview

The Transaction Web Service provides access to all the structural metadata content of the Fusion Registry (including any content that has been subsequently deleted). A Transaction is the submission of a structure, group of structures or data registration.

Querying and Searching All Transactions

Returns a JSON Array of all of the structures in the Registry, filterable by parameter.

Entry Point /ws/registry/tx/searchTransactions
Access Public
Http Method GET
Response Format application/json
Response Statuses

200 - Submission Accepted

Response

The output shows the Date (as a millisecond epoch time), the Transaction Id, the action and the Transaction Type. A typical example: 

 [
   {
     "Date": 1612434466642,
     "Id": 785,
     "Action": "Replace",
     "Type": "Structure Submission"
   },
   {
     "Date": 1612434448408,
     "Id": 784,
     "Action": "Replace",
     "Type": "Structure Submission"
   },
   ...
 ]


HTTP Query Parameters

If no parameters are supplied all transactions known to the Registry will be returned. If any of the filters applied below result in no results, an empty JSON response (HTTP 200) is returned.

Request Parameter Required Purpose
action No Filters the response to only include Transaction for the specified action. Legal values are Append, Replace, FullReplace and Delete.
dateFrom No Filters the response to only include Transactions from the specified time. The value must be specified as the epoch time in milliseconds (e.g. 1609459200000 is the start of the year 2021).
dateTo No Filters the response to only include Transactions up to the specified time. The value must be specified as the epoch time in milliseconds (e.g. 1609459200000 is the start of the year 2021).
max No Limits the returned response to only containing at most the specified value.
orderDesc No The default output is that Transactions are returned in a descending order (most recent first). Supplying false to this parameter reverses the order.
user No Filters the response to only include Transactions for the specified user.

Querying for all URNs

Returns a JSON Array of all the maintainable URNs (both current and deleted) in the Registry.

Entry Point /ws/registry/tx/getAllUrns
Access Public
Http Method GET
Response Format application/json
Response Statuses

200 - Submission Accepted

Response

An alphabetically ordered list of all of the URNs in the system. A typical example: 

 [
   "urn:sdmx:org.sdmx.infomodel.codelist.Codelist=SDMX:CL_BAR(1.0)",
   "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=AAA.SUB1:DF1(1.0)",
   "urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=WB:WDI_POVERTY(1.0)",
   "urn:sdmx:org.sdmx.infomodel.registry.ProvisionAgreement=BIS.LBS:TLBR_WS8_BIS_PH2(1.0)",
   ...
 ]

Querying for a specific URN

Provides information regarding who made changes to a particular structure. It returns the user id (and date, transaction id and action) of who last modified the maintainable with the given URN.

Entry Point /ws/registry/tx/history
Access Public Note: More information is provided if authenticated
Http Method GET
Response Format application/json
Response Statuses

200 - Submission Accepted

400 - Illegal URN

Response

An ordered list of transactions (lowest transaction number first) of the transactions for the specified URN, showing the date, transaction ID and Action. A typical example: 

 [
   {
     "Date": 1612358238673,
     "Id": 449,
     "Action": "Replace",
     "Type": "Structure Submission"
   },
   {
     "Date": 1612358239170,
     "Id": 450,
     "Action": "Delete",
     "Type": "Structure Submission"
   },
   {
     "Date": 1612358239657,
     "Id": 451,
     "Action": "Replace",
     "Type": "Structure Submission"
   },
   ...
 ]

If the query is provided with correct authentication credentials of an administrator then the User ID of the user who performed the change is also returned. An example of this: 

 [
   {
     "Date": 1612358238673,
     "Id": 449,
     "User": "admin1",
     "Action": "Replace",
     "Type": "Structure Submission"
   },

HTTP Query Parameters

Request Parameter Required Purpose
urn Yes The URN of the requested structure.

Querying for a specific Transaction

For a specific Transaction ID, all of the structures can be requested for that Transaction.

Entry Point /ws/registry/tx/transactions
Access Public
Http Method GET
Response Format application/json SDMX
Response Statuses

200 - Submission Accepted

Response

The output will be in the format requested, showing all of the structures for the specific transaction. An example showing SDMX-ML 2.1 for a Dataflow: 

 <?xml version="1.0" encoding="UTF-8"?>
 <mes:RegistryInterface xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xml="http://www.w3.org/XML/1998/namespace" xmlns:mes="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message" xmlns:str="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/structure" xmlns:com="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/common" xsi:schemaLocation="http://www.sdmx.org/resources/sdmxml/schemas/v2_1/message https://registry.sdmx.org/schemas/v2_1/SDMXMessage.xsd">
   <mes:Header>
     <mes:ID>IREF422205</mes:ID>
     <mes:Test>false</mes:Test>
     <mes:Prepared>2021-02-04T12:37:05Z</mes:Prepared>
     <mes:Sender id="REGISTRY1"/>
     <mes:Receiver id="not_supplied"/>
   </mes:Header>
   <mes:SubmitStructureRequest action="Information">
     <str:Structures>
       <str:Dataflows>
         <str:Dataflow urn="urn:sdmx:org.sdmx.infomodel.datastructure.Dataflow=ESTAT:HC02(2.0)" isExternalReference="false" agencyID="ESTAT" id="HC02" isFinal="false" version="2.0">
           <com:Name xml:lang="en">HC02 - Population by Household Status and Educational Attainment</com:Name>
           <str:Structure>
             <Ref package="datastructure" agencyID="ESTAT" id="HC02" version="1.0" class="DataStructure"/>
           </str:Structure>
         </str:Dataflow>
       </str:Dataflows>
     </str:Structures>
   </mes:SubmitStructureRequest>
 </mes:RegistryInterface>

HTTP Query Parameters

Request Parameter Required Purpose
urn Yes The URN of the requested structure.
format No A structure format. Default output is SDMX-ML 2.1. Other options include sdmx-json, fusion-json, sdmx-edi.

Last User to Edit a Structure

Returns only the user id of the last user to edit a specific structure.

Entry Point /ws/registry/tx/userIdFromReg
Access Public
Http Method GET
Response Format application/json

Response

An example output 

  {"userId":"admin1"}

HTTP Query Parameters

Request Parameter Required Purpose
urn Yes The URN of the requested structure.
Retrieved from "https://wiki.sdmxcloud.org/index.php?title=Transaction_Web_Service&oldid=5483"