Transaction Web Service¶

The Transaction Web Service provides access to the registry's transaction history for audit, change discovery and registry replication—the metadata analogue of database replication.

Each transaction represents an atomic change to the registry's content, encompassing structural metadata, metadata sets or data registrations.

The API is organised into two groups:

General purpose API — designed for general integrations that need to discover changes made to the registry, by whom and when, for example user interfaces for exploring the registry's change history.
Transaction collection and content retrieval API — methods for discovering registry changes and separately retrieving the metadata associated with individual transactions. These can support metadata replication and distributed cache consistency, for example by enabling data processing microservices to keep their structure caches up to date.

Paths below are relative to the deployed FMR application.

General purpose API¶

The general purpose methods support user interfaces and general integrations that need to understand what changed in the registry, by whom and when. They allow consumers to search transaction history, inspect changes to individual structures, retrieve historical content, and identify the last editor. Access to user identity information depends on authentication and authorisation, as described below.

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,  
    <span style='color:green'>"User": "admin1",</span>  
    "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
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
txId	Yes	The transaction identifier.
format	No	A structure format. Default structural output is SDMX-ML 3.0. Other options include sdmx-json, fusion-json, sdmx-edi; support depends on the structures in the transaction. Reference metadata is returned as SDMX-JSON v2.

Downloading a Specific Structure from a Transaction¶

Downloads one structure or reference metadata set from a specific transaction as a ZIP file. Unlike /ws/registry/tx/transactions (plural), which retrieves the whole transaction, /ws/registry/tx/transaction (singular) requires both a transaction ID and the URN of the requested item.


Entry Point	`/ws/registry/tx/transaction`
Access	Public, subject to deployment security configuration
HTTP Method	`GET`
Response Format	ZIP download containing a JSON document
Response Statuses	`200` - Download returned; `400` - Missing or invalid parameters, or transaction item could not be obtained

HTTP Query Parameters¶

Request Parameter	Required	Purpose
`txId`	Yes	Integer identifier of the transaction containing the requested item.
`urn`	Yes	Maintainable URN of the structure or reference metadata set to retrieve from that transaction.

Response¶

The ZIP file contains one document:

Item Type	Document Format
Structural metadata, including Fusion-only structures	Fusion-JSON
Reference metadata set	SDMX-JSON metadata v2

The download filename is formed from the item's maintainable ID and the transaction date, followed by .zip. The document inside uses the same base name with the appropriate JSON file extension. Colons in the formatted transaction date are replaced with hyphens for Windows filename compatibility.

This endpoint does not expose a format parameter; the document format is selected according to the item type.

Request Example¶

Retrieve a codelist from transaction 42 (the URN is URL-encoded):

GET /ws/registry/tx/transaction?txId=42&urn=urn%3Asdmx%3Aorg.sdmx.infomodel.codelist.Codelist%3DSDMX%3ACL_EXAMPLE%281.0%29
Accept: */*

Invalid Parameters and Retrieval Errors¶

The service returns HTTP 400 if txId or urn is missing, the URN is not a valid maintainable URN, or the requested transaction item cannot be obtained.

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.

Transaction collection and content retrieval API¶

The Transaction Collection Service provides read-only access to transaction history and individual transaction content through two separate endpoints:

Discover changes: GET /ws/registry/transactions returns transaction IDs, creation timestamps, and affected artefact URNs grouped into deleted (del), inserted (ins), and updated (upd) lists. The optional updatedAfter parameter filters transactions by their creation time. This response contains change information only, not the structures or metadata themselves.
Retrieve transaction content: GET /ws/registry/transactions/{txId} separately retrieves the structural metadata or reference metadata contained in one identified transaction, normally as SDMX-JSON 2.0.0. See Fusion-only structures and replication limitations before relying on this response as a complete copy of a transaction. These serialisation limitations apply to transaction content retrieval, not to the collection's URN lists.

The service does not itself replicate metadata, update external caches, or push change notifications. Those behaviours must be implemented by the consuming application.

Querying the Transaction Collection¶

Returns a JSON array describing recorded transactions. Supply updatedAfter to restrict the result to transactions created at or after a timestamp. If the parameter is omitted or blank, all recorded transactions are queried.


Entry Point	`/ws/registry/transactions`
Access	Public, subject to deployment security configuration
HTTP Method	`GET`
Response Format	`application/json`
Response Statuses	`200` - Transaction collection returned; `400` - Invalid `updatedAfter` value

Response¶

Each array item contains a meta object identifying the transaction and a data object grouping the affected URNs by action.

Example response (illustrative identifiers and URNs):

[
    {
        "meta": {
            "txId": "42",
            "txTs": 1724068800000
        },
        "data": {
            "del": [],
            "ins": [
                "urn:sdmx:org.sdmx.infomodel.codelist.Codelist=SDMX:CL_EXAMPLE(1.0)"
            ],
            "upd": []
        }
    },
    {
        "meta": {
            "txId": "41",
            "txTs": 1724068700000
        },
        "data": {
            "del": [
                "urn:sdmx:org.sdmx.infomodel.codelist.Codelist=SDMX:CL_OLD(1.0)"
            ],
            "ins": [],
            "upd": [
                "urn:sdmx:org.sdmx.infomodel.codelist.Codelist=SDMX:CL_EXISTING(1.0)"
            ]
        }
    }
]

Property	JSON Type	Description
`meta.txId`	String	Transaction identifier. Use this value as `txId` in the individual-transaction URL.
`meta.txTs`	Number	Transaction creation time as milliseconds since the Unix epoch.
`data.del`	Array of strings	URNs of artefacts deleted by the transaction.
`data.ins`	Array of strings	URNs of artefacts inserted/appended by the transaction.
`data.upd`	Array of strings	URNs of artefacts updated/replaced by the transaction.

All three action arrays are present, including when they are empty. No matching transactions produces [] with HTTP status 200. Transactions are returned most recent first.

HTTP Query Parameters¶

Parameter	Required	Description
`updatedAfter`	No	Returns transactions created at or after this time, expressed as epoch milliseconds. If omitted or blank, all transactions are returned.

Request Examples¶

Retrieve all transactions:

GET /ws/registry/transactions
Accept: application/json

Retrieve transactions created at or after an epoch-millisecond timestamp:

GET /ws/registry/transactions?updatedAfter=1724068800000
Accept: application/json

Invalid Parameter Values¶

An invalid epoch-millisecond value returns HTTP 400 with the message:

The parameter 'updatedAfter' must be specified with a legal epoch-millisecond value

Retrieving an Individual Transaction¶

Retrieves the metadata contained in a transaction. Use meta.txId from the collection response as the transaction identifier.


Entry Point	`/ws/registry/transactions/{txId}`
Access	Public, subject to deployment security configuration
HTTP Method	`GET`
Response Format	Normally SDMX-JSON 2.0.0 (structural or reference metadata); see Fusion-only limitations below
Response Statuses	`200` - Transaction document returned; `500` - Transaction could not be retrieved or serialised

Response¶

For content supported by SDMX-JSON, the response format depends on the transaction content:

Transaction Content	Response Content-Type	Response Body
Structural metadata supported by SDMX-JSON v2	`application/json`	An SDMX-JSON structure document containing the supported transaction structures.
Reference metadata	`application/json`	An SDMX-JSON metadata document containing the transaction's metadata sets.

Fusion-only structures and replication limitations¶

Some FMR-specific (non-SDMX) structures can only be serialised as fusion-json. The current implementation does not guarantee a complete SDMX-JSON representation of every structural transaction:

Mixed transactions: when a transaction contains both structures supported by SDMX-JSON v2 and Fusion-only structures, the response contains only the supported structures. The unsupported structures are omitted; they are not embedded as Fusion-JSON, and their omission does not itself cause an error.
Fusion-only transactions: when none of the structures is supported by SDMX-JSON v2 and their configured default format is Fusion-JSON, the structure writer falls back to Fusion-JSON for the response body.
Format identification limitation: the new endpoint currently ignores the actual format returned by the structure writer and uses the requested SDMX-JSON format's generic MIME type, application/json, for the response. Both SDMX-JSON and Fusion-JSON fallback bodies therefore have this Content-Type; the header does not identify the JSON dialect. The SDMX vendor media types declared by the format classes are separate Accept-header values, not the response Content-Type used here. Consumers must not assume that a successful response is necessarily SDMX-JSON. The fallback is writer behaviour, not content negotiation.

The transaction collection's action lists are generated independently of document serialisation, so Fusion-only artefact URNs can appear in data.ins, data.upd, or data.del even when those structures are absent from an SDMX-JSON transaction document. A consumer maintaining a complete cache must account for those URNs rather than treating the retrieved document as exhaustive.

This new endpoint does not expose a format parameter; supplying an Accept header does not select Fusion-JSON. Consumers that need all structures in a transaction, including Fusion-only structures, can use the general purpose transaction retrieval method with an explicit Fusion-JSON format, for example:

GET /ws/registry/tx/transactions?txId=42&format=fusion-json
Accept: */*

HTTP Path Parameters¶

Parameter	Required	Description
`txId`	Yes	Integer transaction identifier.

Request Example¶

Retrieve transaction 42 from the collection example above:

GET /ws/registry/transactions/42
Accept: */*

Retrieval Errors¶

If the transaction cannot be retrieved or serialised, the service returns HTTP 500 with a message such as:

Unable to return transaction for id '42'