Developer guides

Laptop

How to build an application

Last edited at 2022-08-25

Introduction

Building an application for an IOXIO® Dataspace is not much different from building any other web based or mobile application. IOXIO® Dataspace supports both building applications from scratch and upgrading existing applications to take advantage of features from a Dataspace. In fact, it mainly offers a way to extend the functionalities of applications compared to what we see today.

What features does the IOXIO® Dataspace bring to an application?

Data Products

Data Products allows the application to access data in a standardized format, following a data product definition. Multiple different vendors can publish data sources complying with the same definition, making it easy to switch the provider of the data. Data sources are accessed through the product gateway, which validates the request and response data complies with the definition. Data sources can be accessed without any authentication, requiring authentication or by requiring consent.

Authentication

The login portal of an IOXIO® Dataspace can be used for authenticating the users using the OpenID Connect code flow, thus simplifying the authentication process.

Applications are however not required to implement any kind of authentication at all and can use their own authentication solutions as long as they only use data sources which do not require authorization or consent. Using the login portal can however save time compared to implementing an authentication solution from scratch, unify the user experience with other applications on the Dataspace and make it easier to later extend the functionality by using data sources that require authorization or consent.

In case any of the data sources used by the app require a consent from the user, the app needs to use both the login portal for authentication and the consent provider for consents in order to be able to fetch the data product.

Using data products

Finding a data source definition

The first step to use a data product is to find out what data you need and which data source definition provides that data.

There are multiple ways you can view the data source definitions to find the one you need.

API Docs

In the API Docs -> Product Gateway -> Data Products you can view more detailed information about all the data source definitions, as well as see examples of both the request and response payloads for them.

API Documentation screenshot

Data definition viewer

The Data definition viewer is targeted to less technical people and can be used to browse data sources definitions in a simplified and understandable way. This tool is targeted also for business and non-technical users familiarizing and using IOXIO® Dataspace services.

Data definition viewer screenshot


The Select data product definition dropdown can be used to drill down different categories to find data sources by category, like Weather, under which you could find the current weather in metric units.

Data definitions dropdown screenshot


The details view will show you what data is needed as input and what kind of data is included in the response.

Data definition viewer screenshot


GitHub repository

If you prefer to look at the raw OpenAPI Spec files or use some specific tool for inspecting them, you can go to the GitHub repository for the sandbox-definitions. The data source definitions are found in the DataProducts directory.

No matching definition?

If you don't find any data source definition providing the data you need, you can also consult the guide How to create data definitions to create your own definition. The definition alone is of little use unless someone also provides a data source for the data. The guide How to build a data source explains how you or someone else could build a data source for the definition.

Finding an available data source

Log in to the developer portal and navigate to the Available data sources section and use the dropdown to list the available data sources for the desired definition.

Available data sources screenshot


You will get a list of all different data sources providing that data.

If there are no matching sources, you might want to consider building your own data source or request someone to build it, following the How to build a data source guide.

Requesting the data from a data source

If you press the OPEN button next to any of the found items in the developer portal, it will expand and conveniently show you the Request URL for the source:

Screenshot of dropdown for data definition request url

This shows the URL at which you can query the product gateway to get the data from this particular source. For the same definition, the only thing that will change depending on the source is the ?source= query parameter. It's thus easy to later change the source to another that provides the same data.

In order to request the data, you need to know what data to include in the request. The required data is best explained in the Product Gateway API Docs for Data Products. In the section draft/Weather/Current/Metric you can see an example:

API Docs screenshot

The request to data products are always POST requests with the Content-Type set to application/json.

The Authorization and X-Consent-Token headers can be either optional or required.

If the Authorization header is required you will need to pass in the header with a value of the form Bearer <id_token>, where <id_token> is the ID Token the for the logged in user. In practice the header will be of the form Bearer eyJ....

If the X-Consent-Token is required, a Consent Token needs to be passed in the header. Note that the consent token is not prefixed with anything, the token is used as-is in this header.

Later sections of this guide will explain how to authenticate the user to get an ID Token and how to use the Consent Provider to request the consent from a user to get a Consent Token.

The body of the request would need to contain the data described in the definition. For example to query for the weather in Helsinki using the definition mentioned earlier you could use this data:

{
  "lat": 60.192059,
  "lon": 24.945831
}

The response would follow the description in the definition and could for example for Helsinki look like this:

{
  "humidity": 72,
  "pressure": 1007,
  "rain": true,
  "temp": 17.3,
  "windSpeed": 2.1,
  "windDirection": 220
}

In practice, you likely want to do do data product requests through your own backend rather than in your frontend or on the client side. First of all CORS would make it hard to perform the request from the client side, especially in web based applications. In addition, you might want to do some pre- or post-processing to the request, like for example map a city or address to a coordinate (possibly using some other data product) or fetch some additional data. Or maybe just include some of the data in some other response. You might also in some cases want to cache some generic data that doesn't change frequently and doesn't depend on the user. You might also want to monitor your own use of different data sources and even be able to easily switch the source without rolling out an update of the frontend or mobile app.

Authenticating users

There's a separate guide called Use login portal in your application that goes into details on how you register your application and use the login portal for authentication to obtain the id_token for a user.

Using consent

The Consent protocol summary explains how the flow for requesting a consent and the Consent design outlines in more detail the overall design. This guide focuses on implementing the necessary parts of it in your application so you can request the consent from the user, obtain a consent token and use it to fetch the data product.

The data source definition can indicate that the X-Consent-Token is required for a particular definition if it is always required. It's also possible to mark it as optional, in which case each data source can decide if it's required or not. If it's required and missing, the productizer will respond with the status code 403 to the request from the product gateway. The product gateway will use this information and respond to you with the status code 502 and a JSON body with the field status set to 403, which is your indication that consent is required.

Data Source Identifier

For the consent request you will need the Data Source Identifier (DSI) for the data source. It's a Data Product Protocol link of the form dpp://<source>@<dataspace-domain>/<definition>.

Let's see how to create it for this data source:

Screenshot of dropdown element with shareholders data request url


The source is digitalliving:v2, the dataspace-domain (the bare one for the Dataspace, not the one for the product gateway) is sandbox.ioxio-dataspace.com. And the definition is draft/Company/Shareholders. Using the pattern for the Data Source Identifier, it thus becomes dpp://digitalliving:v2@sandbox.ioxio-dataspace.com/draft/Company/Shareholders.

In order to be able to request consent from the user you will need to first authenticate the user and obtain the id_token for the user. This is explained in the Use login portal in your application guide. You will also need the Data Source Identifier described above.

The consent request is created by doing a POST request to the /Consent/Request endpoint on the Consent Provider, for example https://consent.sandbox.ioxio-dataspace.com/Consent/Request. The Content-Type header has to be set to application/json and the Authorization header should contain the id_token of the user (the bare token as-is, not used as a Bearer Token) that you want to request the consent from.

The JSON body of the request should have the dataSource field set to the Data Source Identifier. The body could thus look like this:

{
  "dataSource": "dpp://digitalliving:v2@sandbox.ioxio-dataspace.com/draft/Company/Shareholders"
}

Expressed as a cURL command the whole request would look like this:

curl --request POST \
  --url 'https://consent.sandbox.ioxio-dataspace.com/Consent/Request' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: eyJ...' \
  --data '{"dataSource": "dpp://digitalliving:v2@sandbox.ioxio-dataspace.com/draft/Company/Shareholders"}'

and the response would look similar to this if the user has not yet granted the consent:

{
 "type": "verifyUserConsent", 
 "verifyUrl": "https://consent.sandbox.ioxio-dataspace.com/verify/86c0c7e6-4453-41c3-b20b-857ea41ea67b"
}

In order to request the consent you need to redirect the user to the verifyUrl, but you should also add the query parameter returnUrl to indicate where the consent portal should redirect the user to after giving the consent (or declining it). Thus you would be redirecting the user to something similar to https://consent.sandbox.ioxio-dataspace.com/verify/86c0c7e6-4453-41c3-b20b-857ea41ea67b?returnUrl=https://my-app.example.com

The user will be displayed a prompt to log in:

Screenshot of consent provider

The consent can be granted after logging in:

Screenshot of consent provider after logging in

The user will be redirected back to the return URL with an added ?status=fail or ?status=success query parameter, e.g. either to https://my-app.example.com/?status=fail or https://my-app.example.com/?status=success.

When the user has returned you need to retrieve the consent token. This is done by repeating the same request we did to request the consent earlier. i.e.

curl --request POST \
  --url 'https://consent.sandbox.ioxio-dataspace.com/Consent/Request' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: eyJ...' \
  --data '{"dataSource": "dpp://digitalliving:v2@sandbox.ioxio-dataspace.com/draft/Company/Shareholders"}'

This time the response would look similar to this:

{
  "type": "consentGranted",
  "consentToken": "eyJ..."
}

Note! The same endpoint will return two different types of responses; one with verifyUserConsent containing a verifyUrl and the other with the type consentGranted containing the consentToken. You will need to handle these two cases.

Also note that the consent token has a somewhat short lifetime. However, using the same consent request it's possible to request a new token as long as the consent remains valid.

Once you've got the consent token for the user, you can do a request to the data source through the product gateway. Just remember to add the Authorization header with the id_token as a Bearer Token and the consent token in the X-Consent-Token header.

Using cURL the request would look similar to this:

curl --request POST \
  --url 'https://gateway.sandbox.ioxio-dataspace.com/draft/Company/Shareholders?source=digitalliving:v2' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJ...' \
  --header 'X-Consent-Token: eyJ...' \
  --data '{"companyId": "2464491-9"}'