Macrobond client Web Provider API

Overview

The Macrobond client Web Provider API series provider allows the Macrobond application to use any web service that implements the REST based web API as described below. It offers similar features to the SQL DB Series Provider, but uses a predefined API contract instead of SQL to retrieve the data. It also offers the option of enabling creation and deletion of series as well structured lists of series in the data tree with indentations, emphasized rows and groups of series.

The API uses JSON in responses and POST requests.

There is a Sample server implemented in C#/.NET Core at GitHub.

The API must implement the loadseries and getcapabilities methods. The other methods are optional and will only be called if the server reports that it supports those features via the getcapabilities method.

Method Capability Comment
loadseries Load one or more series given the names of the series
getcapabilties Return a list of capabilities implemented by the server
searchseries search Search for series using keywords entered by the user
loadtree browse Return a tree structure that the user can browse to navigate the database
listseries browse List series in a location of the database tree
createseries editseries Create or update a series
removeseries editseries Remove a series

For communication, both http and https are supported. For authentication, basic http authentication is supported. In this case, https is strongly recommended.

There are some requirements on the database imposed by the Macrobond application:

  • Each time series must have a unique identifier that can be used for retrieving the time series values and metadata. Any lower case characters except double quote and colon are allowed, but it is best if the identifier begins with a-z and continues with a-z, 0-9 or underscore since such identifiers can be used unquoted in the Macrobond application.
  • A time series cannot start before year 1600 or end after year 2499.
  • The time series frequencies are limited to: day, week, month, quarter, 4 months, half year and year.

The is a swagger file for the API here: https://www.macrobond.com/schemas/webclientapi.swagger.json

Configuration

To define what database server to talk to, you define a simple XML file like below:

<?xml version="1.0" encoding="utf-8"?>
<web:WebApiSeriesProvider xmlns:web="http://schemas.mbnd.eu/2019/webapiseriesprovider">
  <web:Host>http://ourdbserver:5555</web:Host>
</web:WebApiSeriesProvider>

In the Macrobond application, in the Settings dialog (Edit|Settings) you specify the path to this configuration file:

Metadata

Each series in the server must contain meta data in the form of a dictionary of string+object. The meta data gives different information about how the series should be handled by the application. Every property in a Meta data dictionary is case sensitive, and they should be written with pascal case. Some meta data properties are optional but there are some that are crucial to make a series work.

The property PrimName is required as a unique identifier of the series. Letters must be lower case.

It is recommended to specify the frequency using the Frequency attribute. The StartDate is required when no list of dates is provided for the series. In most cases you also want to include a Description attribute too.

The Region metadata attribute is the ISO 3166 code of the region. See this list for possible values: Region list

The Currency metadata attribute is the ISO 4217 currency code. This is used for automatic currency conversion in the Macrobond application. See this list for possible values: Currency list

For more information about metadata see: Commonly used metadata

Commands

getcapabilities

Tells the Macrobond application whether this server support browse, search and edit capabilities.

This method must be implemented by the server.

Response

One or more of these boolean values:

  • browse
  • search
  • editseries

If browse is false or not present no tree will be shown in the application. This should be true if loadtree and listseries have been implemented.

If search is false or not present, no search bar will be renderer in the application. This should be true if searchseries has not been implemented.

If editseries is false or not present, the option to create or remove series will not be available to the user. Set to true if the createseries and removeseries have been implemented.

Example

URL:

/getcapabilities

Response:

{
   “browse”: true,
   “search”: true
}

loadseries

Returns a list of series from the server by name.

This method must be implemented by the server.

Parameters

  • n : Array of strings. The identifier of a series. The parameter can be included several times in order to request several series simultaneously.

Response

A list of responses corresponding to each series requested in the same order as in the request. Each element in the list is either a data element with

  • values
  • metaData

or an error element with an error text explaining why the series could not be loaded. You must not include both data and error elements for a series.

There are three options for specifying the calendar:

  • Specify the frequency without list of dates. For daily frequencies you may also specify the DayMask attribute if you do not want the default of Monday-Friday. In this case the calendar will be created from Frequency, StartDate and DayMask.
  • Specify the frequency attribute and a list of dates. For daily frequencies you may also specify the DayMask attribute if you do not want the default of Monday-Friday. In this case the calendar will be created from Frequency, StartDate and DayMask and values will be made available for the periods corresponding to the specified dates. Any “gaps” in the set of dates will be gaps in the resulting calendar. The StartDate metadata must reference the first observation.
  • Include a list of dates, but do not specify the frequency. The application will guess the frequency based on the provided set of observations. It will pick the lowest frequency to cover the specified dates without duplicates. The StartDate metadata must reference the first observation.

The DayMask metadata is used for daily series. It is a bitmask as an integer where Sunday is the bit with value 1. A mask for Monday-Friday is thus 62. A string can be passed instead of a bitmask and should then have the weekdays in English separated with space. For instance Monday Tuesday Wednesday Thursday Friday. Such a string will be converted to the corresponding bitmask.

Example

URL:

/loadseries?n=name1&n=name2&n=name3

Response:

[
  {
    “data”: {
      “values”: [600.0, 570.0, 630.0, 450.0, 200.0],
      “metaData”: {
        “Description”: “0-7 Years”,
        “PrimName”: “name1”,
        “Frequency”: “annual”,
        “StartDate”: “1990-01-01T00:00:00”,
      }
    }
  },
  {
    “data”: {
      “values”: [10, 11, 12, 13],
      “dates”: [“1990-01-01T00:00:00", "1990-02-01T00:00:00", "1990-04-01T00:00:00", "1990-05-01T00:00:00”],
      “metaData”: {
        “Description”: “8-12 Years”,
        “PrimName”: “name2”,
        “Frequency”: “monthly”
      }
    }
  },
  {
    “error”: “Series name3 not found”
  }
]

searchseries

Gets a list of meta data of series from given string.

Parameters

  • query: The text entered by the user

Response

The response is a list of metadata sets. The metadata must contain Description and PrimName.

The Macrobond application can show some additional attributes as columns in the list of a search result. These are optional. Frequency, StartDate, EndDate, Currency, DisplayUnit, Region, LastValue, PreviousLastValue, Class

Example

URL:

/searchseries?query=US

Response:

[
   {
      “Description”: “US Main Regressions”,
      “PrimName”: “series1”
      “Frequency”: “annual”,
   },
   {
      “Description”: “US Main Regressions”,
      “PrimName”: “series2”
   }
]

loadtree

Returns a tree or subtree from the database. If the tree is large or costly to load from the database, it can be split up into sub trees that will be loaded when the user expands them.

Parameter

  • reference: Optional. If specified, load the referenced sub tree. If not specified, load the root of the tree.

Response

The returned data forms a nested tree which is used to create a database tree in the application UI.

Each node in the tree can contain either Children, ChildrenReference or SeriesReference.

A Children element contains a nested list of the tree.

A ChildrenReference contains a deferred nested list of the tree. A request for the branch will be sent as a loadtree request to the server and the specified reference will be included in the query.

The leaves of the tree contain an element called SeriesReference. When the user clicks on such a branch in the tree a listseries request, including the specified reference, is sent to the server to retrieve the list of series to present to the user.

Example

URLs:

/loadtree
/loadtree?reference=treeNodeReference

Response:

[
   {
      “Description”: “First folder”,
      “SeriesReference”: “ref1”
   },
   {
      “Description”: “Second folder”,
      “Children”:
      [
         {
            “Description”: “First sub folder”,
            “SeriesReference”: “ref2”
         },
         {
            “Description”: “Second sub folder”,
            “ChildrenReference”: “sub2”
         },
      ]
   },
]

listseries

Lists all series for a leaf in the data tree.

The application will call this method when the user selects a leaf in the data tree.

Parameters

  • reference: The reference from the leaf in the data tree.

Response

The following elements are required:

  • groups
  • entityMeta
  • names

The list of series will be presented in the Macrobond application when a leaf in the data tree is selected.

Aspects

The result can optionally contain “aspects” will be presented as tabs in the UI. For example “NSA, Monthly” in the image above.

The presented list below the aspect tabs is the same for all tabs, but refers to different series.

If there is only one aspect then aspects can omitted.

For every aspect there must be as many metadata collections in each row of series. If there are two aspects then every row of series must contain two collections, if there are three aspects then every row must contain three collections etc.

If there are no aspects, the entityMeta element contains only one collection.

The response is a list of metadata sets. The metadata must contain Description and PrimName.

The Macrobond application can show some additional attributes as columns in the list of a search result. These are optional. FrequencyStartDateEndDateCurrencyDisplayUnitRegionLastValuePreviousLastValueClass

Groups

The list may be divided into groups. If there is only one group then the name property of that group can be omitted.

Formatting

The entries in the list can be indented by specifying an indentation level.

Entries can be emphasized like “Food & Beverages” in the image above.

Additional space can be added above an entry, like for “Food” in the image, but specifying spaceAbove as true.

Example

URL:

/listseries?reference=serieslistreference

Response:

{
   “aspects”:
   [
      {
         “name”: “Tab 1”,
         “description”: “Tooltip of tab a”
      },
      {
         “name”: “Tab 2”,
         “description”: “Tooltip of tab b”
      },
   ],
   “groups”:
   [
      {
         “name”: “The first group”,
         “series”:
         [
            {
               “description”: “Variable 1”,
               “indentation”: 3,
               “emphasized”: false,
               “spaceAbove”: false,
               “entityMeta”: [
                 {
                   “PrimName”: “series1a”, 
                   “Description”: “Total, Goods”,
                   “Region”: “se”
                 },
                 {
                  “PrimName”: “series1b”,
                   “Description”: “Total, Goods”,
                   “Region”: “se”
                 } 
               ]
            }
         ]
      }
   ]
}

createseries

Creates a new in-house series.

Parameters

  • lastModified : Timestamp. When replacing an existing series, this value reflects the LastModifiedTimeStamp metadata, if present, of the series edited by the user. It will be not be included when creating a new series. It is included when overwriting an existing series unless the forceReplace parameter is true.
  • forceReplace : Boolean. If this parameter is included and set to true, then the existing series should be overwritten. If the series does not already exist, HTTP status 404 Not Found should be returned.

Response

Success (200): Must return new lastModified time for the series.

Not Found (404): If lastModified has a value or forceReplace is true but the series could not be found.

Conflict (409): If the lastModified parameter does not match the actual timestamp of the stored series. This means that someone else might be editing the same series.

Example

URL:

/createseries

Post data:

{
  "values": [
     "767161, 782911, 866119, 929586"],
  "metaData": {
    "PrimName": "myseries1",
    "Description": "Total",
    "StartDate": "2016-01-01T00:00:00",
    "Frequency": "monthly",
    "LastModifiedTimeStamp": "2019-12-04T00:00:00"
  },
  "dates": [
     "2016-01-01T00:00:00", "2017-01-01T00:00:00", "2018-01-01T00:00:00", "2019-01-01T00:00:00"]
}

Response:

2019-12-04T00:00:00

removeseries

Removes a series.

Parameters

  • name : The name of the series to be removed

Response

Success (200): The series was removed.

Not Found (404): Series with given name parameter could not be found.

Example

URL:

/removeseries?name=myseries1