Skip to main content

Client REST API

The Promaster API can be used by applications to fetch data that has been stored in Promaster. There are different versions of the API tht have slightly different interface. See more details below.

Structure

The structure of the API is this

  • Marker
    • Release
      • Product
        • Table

The calling application should fetch a release from promaster. Each release contains an immutable snapshot of data for each product. One release can contain multiple products. It is not required that a release contains all products, it may contain only some products. Each product contains a list of it's tables.

Marker

A marker is used to point to a release. A marker alawys have the same identification but it can be set to point to releases with different identification.

When a new release of the data is made in Promaster, you may want the calling application to start using the new release. If the identification of the release to fetch is part of the calling application's code or config, that would mean that the calling application's code or config would have to be updated every time a new release is made in Promaster. In order to avoid this the calling application should alwyas fetch from a marker instead of fetching directly from a release. If the calling application uses the marker as a starting point for it's fetching, then moving the marker in Promaster is enough to have the application use a different release.

URL calls API v3

API v3 is used for accessing product data that is published to the public API-server. Only data that is published will be available. Only releases that are pointed to from a marker are available. Other releases are removed from the API-server to maintain space on the server.

It means that if a marker is moved so that a previously published release is no longer appointed by a marker then this release will be removed.

Calling applications should always start fetching with a named marker. The URL to reach a named marker is:

https://public-api.promaster.se/rest/v3/{tenantId}/public/markers/{markerName}

For testing purposes it is also possible to leave out the {markerName} part to retieve a list of all available markers.

An example result from the above URL:

{
  "marker_name": "poc",
  "release_name": "1.0.0",
  "release_id": "AA16B7E0-0A80-11E7-851F-DB51BD7C4D23",
  "products": "https://public-api.promaster.se/rest/v3/{tenantId}/public/releases/AA16B7E0-0A80-11E7-851F-DB51BD7C4D23"
}

The products field links to the location of the list of products that are included in the release the marker is currently pointing to. Following this URL will give a response like this:

[
  {
    "id": "ABCDAFB0-0F80-11E7-9011-EFA8363C8A72",
    "key": "PRODUCT_A",
    "name": "PRODUCT_A",
    "retired": false,
    "transaction_id": "322309",
    "tables": "https://public-api.promaster.se/rest/v3{tenantId}/public/transactions/322309/products/ABCDAFB0-0F80-11E7-9011-EFA8363C8A72/tables",
    "all_tables": "https://public-api.promaster.se/rest/v3/{tenantId}/public/transactions/322309/products/ABCDAFB0-0F80-11E7-9011-EFA8363C8A72"
  },
  {
    "id": "ABC753A0-9A50-11E6-E0F9-3D31D4CBCF5A",
    "key": "PRODUCT_B",
    "name": "PRODUCT_B",
    "retired": false,
    "transaction_id": "322309",
    "tables": "https://public-api.promaster.se/rest/v3/{tenantId}/public/transactions/322309/products/ABC753A0-9A50-11E6-E0F9-3D31D4CBCF5A/tables",
    "all_tables": "https://public-api.promaster.se/rest/v3/{tenantId}/public/transactions/322309/products/ABC753A0-9A50-11E6-E0F9-3D31D4CBCF5A"
  }
]

The tables field in this response links to a list of tables available on each product, while the all_tables field list to a link with all tables and their rows. So if the calling application only wants to fetch data for a single table it should fetch the tables URL and from there it will find an URL to each table's rows. If it wants to fetch all data for the product it should fetch the URL in the all_tables field.