Warning

This is a development version of the documentation and may contain inaccuracies! Please find the official documentation at https://opendatahub.readthedocs.io/en/latest/

How to set up Postman (API Development Environment)?

Postman is a popular API development environment, that is, a tool that is used (among other useful features) to ease the interaction with API calls to remote sites. In this tutorial, we show the few steps necessary to set Postman to connect to the Open Data Hub datasets in both the mobility and tourism domains.

In the remainder of this tutorial, we will use as example the E-chargin station dataset, located at http://ipchannels.integreen-life.bz.it/emobility/swagger-ui.html for the mobility domain and the Accommodation dataset, located at http://tourism.opendatahub.bz.it/swagger/ui/index#/Accommodation.

Initial Setup

After Postman has been launched, click on the New button, then on Request to start the configuration of the Open Data Hub endpoints, like shown in Figure 27.

../_images/newrequest.png

Figure 27 Start of a new request creation.

In the dialog window that opens, write the URL of the endpoint in the Request name textfield and assign it in the ODH collection, see Figure Figure 28.

Hint

If no collection has already been created, create one by clicking on + Create collection, then write ODH and confirm.

Click on Save to ODH to start querying the endpoint.

Repeat the procedure for the Accommodation dataset and for any other dataset you want to query.

../_images/newendpoint.png

Figure 28 Defining a new endpoint in the mobility domain.

It is now possible to start querying the endpoints, by providing next to the GET button the corresponding call, like shown in Figure 29 for the E-charging station dataset and in Figure 29 for the Accommodation dataset. However, while the former images shows a set of results, on the latter appears the message Authorization has been denied for this request. and the status 401 Unauthorized.

../_images/postman8.png

Figure 29 Querying the E-charging station endpoint.

../_images/postman1.png

Figure 30 Querying the Accommodation endpoint.

The reason is that the data contained in that dataset have not (yet) been published as open data, therefore authentication is necessary. This is where Postman proves useful, since it can request authentication tokens (OAuth2 in the case of Open Data Hub), store them, and use them whenever the are needed.

Getting a new Authorisation Token

To request a new authorisation token, click on Authorization right below the GET request, then select OAuth 2.0 as the Type.

Now, in the right-hand side of the window, write the URL that manages the tokens (for the tourism domain, this is http://tourism.opendatahub.bz.it/token and click on the Get New Access Token button (Figure 31).

../_images/postman3.png

Figure 31 Requesting an access token.

In the dialog window that opens fill in all the necessary fields, like shown in Figure 32, selecting Password Credentials as the Grant Type, then click on Request Token. Make sure you have received the username and password to obtain the token, and give it a name easy to remember.

../_images/postman4.png

Figure 32 A filled-in token request.

If your credentials are correct and the request is successful, the dialog window will be replaced by another one containing the access token and a few details about it, including its validity and expire date, see Figure 33 and Figure 34.

../_images/postman5.png

Figure 33 An access token.

../_images/postman6.png

Figure 34 Information about an access token

It is now possible to select the token: Select Opendatahub Tourism from the Available Tokens drop-down menu (see Figure 31), click on Body and repeat the GET request. You should be able to see now the data in the dataset, like shown in Figure 35.

../_images/postman7.png

Figure 35 Access to data requiring authorisation.