Introduction

This is the website of the Open Data Hub documentation repository, a collection of resources about the Open Data Hub project. The website serves as the main resource portal for everyone interested in deploying apps based on datasets & APIs provided by the Open Data Hub team.

The technical stuff is composed of:

  • Catalogue of available datasets.
  • How-tos.
  • API documentation.
  • Links to the full API documentation.

Project Overview

In this section you can find an overview of the Open Data Hub Project and an introduction to the available Domains, APIs, and Datasets.

_images/domain.png

Figure 1 An overview of the Open Data Hub Project.

In a nutshell, the Open Data Hub Project takes data from multiple domains (mobility, tourism, meteo), makes them available through the Open Data Hub with the purpose to allow third party developers (or any interested user) to use them within their own projects, using the available APIs.

Domains with Available Datasets

This part has been moved to its own section

Available APIs

The API of a software contains the definition of methods and of their signatures, that can be invoked to retrieve data from the web services provided by the software itself. The signature of each method defines how to invoke the method (i.e., the name of the method), which parameters should be supplied (i.e., their names and types, if they are mandatory or not, and what the method returns (i.e., the type and format of the output produced by the method. By using an API, it is possible to receive data from the web service and process them.

Currently, the following APIs are available from the Open Data Hub:

  1. Mobility APIs
  2. SASAbus APIs
  3. Tourism APIs.

The first and second APIs provide datasets that belong to the Mobility Domain, while the third one to datasets in the Tourism Domain.

The Mobility APIs allow to access real-time data of the datasets concerning the e-mobility, including data about e-charging stations, availability of plugs to recharge e-cars, and so on.

The SASAbus APIs are part of the Mobility domain and allow to access various type of data about buses and station.

The Tourism API allows to access locations (of hotels, museums, events, and so on), points of interests, and a number of other information about the tourism in South Tyrol.

Authentication

Note

The authentication layer is currently intended for internal use only.

Authentication in Open Data Hub is mainly used in the part of the Big Data Platform which exposes data to the consumer, which means by the Reader and in every single webservice accessing the Reader, to allow the access to closed data in each dataset only to those who are allowed to.

There are currently two different authentication methods available:

  • The Basic Authentication, defined in RFC 7617, requires that anyone who wants to access resources supply a valid username and password. Basic authentication is used for the datasets in the tourism domain,
  • The OAuth2 Authentication follows the RFC 6749 and is used for all the datasets in the mobility domain.

The OAuth2 authentication mechanism Authentication tokens are based on JSON Web Token (JWT) as defined in RFC 7519#section-3, to send claims.

For those not familiar with the OAuth2 mechanism, here is a quick description of the client-server interaction:

  1. The client requests the permission to access restricted resources to the authorisation server.

  2. The authorisation server replies with a refresh token and an access token. The access token contains an expire date.

  3. The access token can now be used to access protected resources on the resource server. To be able to use the access token, add it as a Bearer token in the Authorization header of the HTTP call. Bearer is a means to use tokens in HTTP transactions. The complete specification can be found in RFC 6750.

  4. If the access token has expired, you’ll get a HTTP 401 Unauthorized response. In this case you need to request a new access-token, passing your refresh token in the Authorization header as Bearer token. As an example, in Open Data Hub datasets Bearer tokens can be inserted in a curl call like follows:

    curl -X GET "$HTTP_URL_WITH_GET_PARAMETERS" -H "accept: */*" -H "Authorization: Bearer $TOKEN"
    

Here, $HTTP_URL_WITH_GET_PARAMETERS is the URL containing the API call and “$TOKEN” is the string of the token.