Transaction-API specification

Transaction-API is one method to transfer data to FinBIF. Using this method, the original data source implements the Transaction-API and FinBIF DW periodically queries it for new data. (When using /push, FinBIF has implemented the push-API and original data source sends data at it's own schedule.)

General

The basic principle is that the original data source must keep track of all inserts, updates and deletions. These form a transaction log and each transaction will be given an id (numeric, increasing). The DW will query the Transaction-API for the next N transactions and stores the highest transaction-id that is up to date with the DW.

It is important to note the difference between document-id and transaction-id. Each document must have a unique identifier, and the same document can have many transactions (first insert, then updates and finally a delete).

Transaction-API specification consists of two endpoints:

  • ATOM-feed - A list of transactions, starting from a certain transaction-id, limited by limit parameter.
  • Document-endpoint - Returns the current state of an entire document, serialized in one of the supported document formats (more formats and support for custom formats can be added).

If the data source contains non-public data, both endpoints can be set to use HTTP Basic -authentication.

ATOM-feed

HTTP GET /transaction?from=1234&limit=50

Will contain list of transactions, starting (including) the id given in form parameter value. Response follows the ATOM-standard.

Example response: transaction-ATOM-feed.xml

Author, id, link, title and updated are required elements of the ATOM standard, but Transaction-API will not use their contents in any way.

Entry:

  • id - Transaction-id.
  • link - Link to Document-endoint, points to the document affected by this transaction (will not be accessed in case of DELETE).
  • title - Required but not used. Can contain for example the internal document id.
  • updated - Required but not used. Time of the transaction.
  • summary - INSERT|UPDATE|DELETE.

Successful request should return HTTP 200 and unsuccessful something else.

Document-endpoint

The address to the document endpoint is given in the ATOM feed link-element. The structure of the link can be anything. It must be a full URI (not relative). Successful request should return HTTP 200 and the current contents of the document. Deleted documents can return HTTP 404. Unsuccessful requests should return something else.