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 EditorNew 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.