Skip to content

What is needed - for Service Providers

In a nutshell

To register your service at the Data Market Austria (DMA) requires:

1) A DMA Service API description, which usually is created before you implement your service.
If you already have an OpenAPI description, or OpenAPI version 3 description it can be easily extended to a DMA Service API description.

2) An up and running service comprising:
a valid URL for a health check
a describtion URL of your service, and
a valid e-mail address to be notified in case your service is down.

Most important technical ingredient to create and provide a Data Market Austria service is, to have an API description of your service. It forms the contract between client and server - consumer and provider.
Therefore, the DMA Service API Editor is in place, and allows you as a service provider to

  • create an API description from scratch - based on a DMA service template v2 (or v3)
  • use your existing API description as a starting point and extend it to a DMA service description

Since the DMA service creation workflow requires an already running service - at least an URL that responds to requests, the DMA Service API Editor enables you to generate server source code out of your DMA service description.

Once you have created your service API description, you also have to provide additional metadata, which is used to make your service searchable.


NOTE, that Data Market Austria does NOT store your Service API Description.
It is your responsibility as Service Provider to handle and save your description file correctly on premise.


This is especially important, as only a checksum of your API description is calculated and stored as contract relevant information within the Data Market Austria blockchain.

Create an API description from scratch

To start with a minimum template, DMA Service API Editor offers the following functions within its File Menu:

  • New API description v2, which loads a template in OpenAPI v2 version (aka Swagger 2.0) into the Editor
  • New API description v3, which loads a template in OpenAPI v3 into the Editor

The difference between v2 and v3 is described here and is - roughly spoken - that v3 simplifies the layout of an API description, but at the same time, also allows more complexity. These additional complex possibilities are often not yet available in the source code generators for the different programming languages.

Although the description templates come with some pre-filled information, the x-dma-metadata section deliberately has some gaps, that have to be filled by the service provider. Theses missing pieces of information are shown on the top right side of the Service API Editor validation pane.

After importing your API description, tha DMA Service API Editor will usually complain about missing items, which may be optional in the OpenAPI standard, but are mandatory according to the DMA service specification.

Use your existing API description

If you are lucky to already have an existing API description of your service in YAML file format, just

  • Drag and drop the API description into the left pane of the DMA Service API Editor, or
  • Import it from an URL with the File/Import URL menu function, or
  • Import it from file via File/Import File function

Alternatively, if your API description is stored in JSON file format, the DMA Service API Editor ask you to convert it on the fly into the (more convenient) YAML format.

Adding missing metadata

Apart from mandatory OpenAPI items,

  • externalDocs
  • info.contact
  • info.license

there is the info.x-dma-metadata property containing

  x-dma-metadata:
    publisher: publisher
    theme:
      - Unknown
    pricemodel: simple
    servicetype: Calculation
    qualityrating: 1
    created: DMA-date

which can be inserted using the Editor's Edit/Add DMA Metadata menu function.

How to handle missing API description data

In order to find out, what exactly is expected by the DMA Service API Editor validation handler, we suggest the following 3 step approach:

Most typically, if an object is missing (shown by the error message on the top right): e.g.

Schema error
should have required property 'externalDocs'
missingProperty: externalDocs
Jump to line 0

you place the cursor at the requested line - if it's line 0 then maybe a line after the initial API definition tag at line 1 and - as a first step - enter the missing property

externalDocs:

which leads to a different validation handler message

Schema error at externalDocs
should be object
Jump to line 0

This can be handled by entering a dummy test object - as step two - in the subsequent line (beware of indentation): e.g.

externalDocs:
    test: test

which triggers the validator to come up with the message, what is really expected for object:

Schema error at externalDocs
should have required property 'url'
missingProperty: url
Jump to line 2

So, in step three, fill in the proper url and remove the previously added dummy test object.

externalDocs:
    url: https:/doc.myservice.com/api-description.html

The same approach can be applied for simple types like string which requires a one-liner:

   key: string value

For info.contact use the url property, and for info.license use the name property.

Please keep in mind, that YAML is sensitive to indentation, and also, that key - value pairs must be separated by a : i.e. colon + blank.

Submitting your service to Data Market Austria

Once you have your service up and running, you can submit it to the Data Market Austria.
To do so, requires you to log into the DMA Portal and then select the Dashboard/Create Service menu function, which guides you to the list of your services.

Note, that you need to have sufficient permission to administrate services.

By clicking the + Create button you open a window for entering

  • the name of your service (must be unique)
  • a description of your service (which is copied into your API description afterwards)
  • the web-URL of your service (must exist and respond with HTTP 200)
  • a health-URL, (must exist as well and respond with HTTP 200)
  • a poll frequency (in seconds) for polling the health-URL, and
  • a notify E-mail address, used to inform you, in case the health check fails

These bits of information are transferred to the DMA Service API Editor, which is displayed after you push the 📋 Save button.

The DMA Service API Editor is intended to merge the previously entered information of your service (metadata) with the API description of your service.

Therefore, you load your API description, either by

  • drag and drop, or by
  • File/Import Url or
  • File/Import File

into the editor and make sure, that your description is without errors or warnings.

If you then choose the Submit/Submit to DMA menu function, the DMA Service API Editor fills in the missing pieces of information into your API description and calculates a checksum over your API description.

If everything worked out correctly, you have to acknowledge the submission once again, which creates two data packages 1) the data package forwarded to the DMA Contract Management 2) the transformed API description, which you have to download and store safely.

Transformation means, that your service domain located in OpenAPI v2 format

host: the-hostname-of-your-service

or OpenAPI v3 format

hosts: 
 - the-hostname-of-your-service

has been replaced by the DMA Gateway host, so that you can provide your modified API description directly to your service customers

  • either by publishing it on your service description webpage, or
  • if your service is intended for an exclusive circle of customers only, by sending it over private communication channels.

Note, that you have to make sure, you store your API description on your premise, as Data Market Austria does not store any contract relevant API information, except the API checksum.


Service Contract Management

Submitting the service API description to Data Market Austria requires the
API description to be linked with a contract, or a set of possible contracts. This workflow step is done in the subsequent DMA Service Contract Management. It makes sure, that your API description - represented by a calculated checksum - is part of the contract, which is then stored within the Data Market Austria blockchain.

See Blockchain for more information.

API Gateway Management

Another important step within the service creation workflow is: to register your service within the Data Market Austria Gateway. This makes sure, only DMA participants get access to your service, after they have fulfilled monetary obligations.

API Service Description Harvesting

Final step within the service creation workflow to make your service visible and searchable is, to add your service description to the Data Market Austria Service-catalog.