# RESTful API

{% hint style="success" %}

#### **Weather API**

Accurate weather information and forecasts are essential elements in critical decision-making scenarios. Both enterprises and individual consumers rely on current and future weather patterns to run their daily operations and manage risks successfully.

As such, the increased demand for accurate weather information has pushed the developer community to invest in building reliable weather apps.

So in this Use Case we're going to:

* use a weather API.
* pull the data into PDI.
* display dataset in a CDE dashboard - Pentaho Server service.
  {% endhint %}

<figure><img src="/files/6nZEFbRc1RQPx16eWT1w" alt=""><figcaption><p>CDE weather dashboard</p></figcaption></figure>

***

{% tabs %}
{% tab title="Setup" %}
{% hint style="success" %}
The following section is for Reference only.

The CDE has been activated.

You may require to create an Openweathermap account.
{% endhint %}

Follow the steps outlined below to activate CDE and test the API call with Postman.

<figure><img src="/files/lrl2qcCsOkIbZFHzvXR5" alt=""><figcaption><p>Postman</p></figcaption></figure>

{% tabs %}
{% tab title="1. Activate CDE" %}
{% hint style="info" %}
To activate the Community Dashboard Editor (CDE) plugin, you will need to change the configuration of several .xml files in the Pentaho solutions folder as described below. Verify that you have the appropriate permissions to read, write, and execute commands in the specified directories in the instructions.
{% endhint %}

1. Ensure the Pentaho Server is stopped.

```bash
cd
cd /opt/pentaho/server/pentaho-server
sudo ./stop-pentaho.sh
```

2. Uncomment the following lines:

```bash
cd
cd /opt/pentaho/server/pentaho-server/pentaho-solutions/system/pentaho-cdf-dd
sudo nano plugin.xml
```

3. Locate the following two commented blocks in this file and remove the comment tags from these blocks.

```xml
<operation>
    <id>EDIT</id>
    <perspective>wcdf.edit</perspective>
</operation>
```

```xml
<overlays>
    <overlay id="launch" resourcebundle="content/pentaho-cdf-dd/lang/messages">
        <button id="launch_new_cde" label="${Launcher.CDE}" command="Home.openFile('${Launcher.CDE}', '${Launcher.CDE_TOOLTIP}', 'api/repos/wcdf/new');$('#btnCreateNew').popover('hide');"/>
    </overlay>
    <overlay id="startup.cde_dashboard"  resourcebundle="content/pentaho-cdf-dd/lang/messages" priority="1">
        <menubar id="newmenu">
            <menuitem id="new-cde_dashboard" label="${Launcher.CDE}" command="mantleXulHandler.openUrl('${Launcher.CDE}','${Launcher.CDE_TOOLTIP}','api/repos/wcdf/new')" />
        </menubar>
    </overlay>
</overlays>
```

4. Save.

```
CTRL + O
Enter
CTRL + X
```

5. Uncomment the following lines:

```bash
cd
cd /opt/pentaho/server/pentaho-server/pentaho-solutions/system/pentaho-cdf-dd
sudo nano settings.xml
```

3. Locate the block at end of the file, 'Defining the new-toolbar-button' and remove the comments tags from this block

```
<new-toolbar-button>1,New CDE Dashboard,CDE Dashboard,api/repos/wcdf/new</new-toolbar-button>
```

4. Locate the block at end of the file, 'Defining the new-toolbar-button' and remove the comments tags from this block.
5. Save.

```
CTRL + O
Enter
CTRL + X
```

7. Save your changes.
8. Restart the Pentaho Server.

```bash
cd
cd /opt/pentaho/server/pentaho-server
sudo ./start-pentaho.sh
```

***

**Community Dashboard Editor (CDE)**

To verify CDE is activated, do the following.

1. Log on to the [Pentaho User Console](https://help.pentaho.com/Documentation/8.0/Setup/Evaluation/Tutorials/0D0/020).
2. From the Home page, click the Create New button.
3. From the menu that displays, select the New CDE Dashboard option. You can now begin creating your first CDE dashboard.

<figure><img src="/files/s3PorxsSR7QEGx5VysUv" alt="" width="375"><figcaption><p>CDE Dashboard</p></figcaption></figure>
{% endtab %}

{% tab title="2. Weather API" %}

1. Sign up for a free Openweather account.

{% embed url="<https://openweathermap.org/>" %}

2. Once registered, generate an API key.

<figure><img src="/files/F1Mq777mdIYJx5OdR3NF" alt=""><figcaption><p>Generate a key</p></figcaption></figure>

3. Read the API documentation for deployment - Geocoding

{% embed url="<https://openweathermap.org/api/geocoding-api#direct_name_how>" %}
Link to Openweathermap API
{% endembed %}

```
http://api.openweathermap.org/geo/1.0/direct?q={city name},{state code},{country code}&limit={limit}&appid={API key}
```

<table><thead><tr><th width="156">Parameters</th><th width="138"></th><th>Description</th></tr></thead><tbody><tr><td><code>q</code></td><td>required</td><td>City name, state code (only for the US) and country code divided by comma. Please use ISO 3166 country codes.</td></tr><tr><td><code>appid</code></td><td>required</td><td>Your unique API key (you can always find it on your account page under the <a href="https://home.openweathermap.org/api_keys">"API key" tab</a>)</td></tr><tr><td><code>limit</code></td><td>optional</td><td>Number of the locations in the API response (up to 5 results can be returned in the API response)</td></tr></tbody></table>

**Example**

```
http://api.openweathermap.org/geo/1.0/direct?q=London&limit=5&appid={API key}
```

{% endtab %}

{% tab title="3. Postman" %}
{% hint style="info" %}
Postman is an [API platform](https://www.postman.com/api-platform/) for building and using APIs.
{% endhint %}

1. Sign up - for free - & download Postman.

{% embed url="<https://www.postman.com/>" %}

{% hint style="info" %}
You can also install Postman as a VS Extension or from Snap.
{% endhint %}

2. Once logged into your account you can test your API weather call and test the output of various parameters.

<figure><img src="/files/wc1LPpZlBv5zuVaPAZAH" alt=""><figcaption><p>Test</p></figcaption></figure>

{% hint style="warning" %}
The new 'One Call' API requires the location latitude & logitude.

This method usues a deprecated Geocoding API to resolve city, state, country - ISO 3166.
{% endhint %}

<table><thead><tr><th width="477">Query Params</th><th>Value</th></tr></thead><tbody><tr><td>https://api.openweathermap.org/data/2.5/weather?</td><td></td></tr><tr><td>q=</td><td></td></tr><tr><td>{city name}</td><td>london</td></tr><tr><td>{state code}</td><td>England</td></tr><tr><td>{country code}</td><td>GB</td></tr><tr><td>appid</td><td>{API key}</td></tr></tbody></table>

<figure><img src="/files/lrl2qcCsOkIbZFHzvXR5" alt=""><figcaption></figcaption></figure>

Optional Params

3. Edit the query to set the mode & units.

<table><thead><tr><th width="144">Params</th><th>Description</th></tr></thead><tbody><tr><td>mode</td><td>Possible values are <strong>xml</strong> and <strong>html</strong>. If you don't use the mode parameter format is <strong>JSON</strong> by default.</td></tr><tr><td>units</td><td>Units of measurement. <strong>standard</strong>, <strong>metric</strong> and <strong>imperial</strong> units are available. If you do not use the units parameter, standard units will be applied by default.</td></tr><tr><td>lang</td><td>You can use this parameter to get the output in your language.</td></tr></tbody></table>

```
https://api.openweathermap.org/data/2.5/weather?q={city name},{state code},{country code}&appid={API key}&mode=xml&units=metric
```

x
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Resources**

REST API documentation API information for building custom solutions of Pentaho products.
{% endhint %}

{% embed url="<https://docs.pentaho.com/rest-api>" %}

{% embed url="<https://docs.pentaho.com/pba-ctools/pentaho-cdf-api>" %}

{% embed url="<https://docs.pentaho.com/pdia-admin/readme/platform-javascript-apis>" %}
{% endtab %}

{% tab title="Pentaho Data Integration" %}
{% hint style="info" %}
The CDE is a Pentaho service.
{% endhint %}

x

x

{% tabs %}
{% tab title="1. Transformation" %}

<figure><img src="/files/fgbTi2EYu9Y3UswbEI2q" alt=""><figcaption><p>weather API</p></figcaption></figure>

**Weather API**

1. Start Pentaho Server.

```bash
cd
cd /Scripts
./start_pro.sh
```

2. Open the following transformation in Pentaho Data Integration.

\~/Workshop--Data-Integration/Labs/Module 7 - Workflows/API/tr\_weather\_cda.ktr

3. Browse through the following steps.

{% tabs %}
{% tab title="Get variables" %}
{% hint style="info" %}
As you already know, Kettle variables can be used in Jobs and Transformations wherever you see a dollar sign. There is one more way to use variables - getting their values as fields of your stream. For this, you have to use the Get Variables step.

With the Get Variables step, you can get the value for one or more variables. The kind of variable can be any of the Kettle variables types you just learned the variables defined in the kettle.properties file, internal variables, for example, ${user.dir}, named parameters, or other Kettle variables.
{% endhint %}

1. Double-click on the step to view settings.

<figure><img src="/files/PHO2kygoymnZOiSRZS8V" alt=""><figcaption><p>Get variables</p></figcaption></figure>

2. The variables & default values are pulled from 'Named Parameters' set in the Transformation properties.

<figure><img src="/files/rvFXv2FQ6FFSLcDBKPT2" alt=""><figcaption><p>Default Named parameters</p></figcaption></figure>
{% endtab %}

{% tab title="REST Client" %}
{% hint style="info" %}
The REST Client transformation step enables you to consume RESTfull services.

For a simple http GET request you can also use: http client step.
{% endhint %}

1. Double-click on the step to view settings.

<figure><img src="/files/WWIyX7kNOkOCN4flti1G" alt=""><figcaption><p>HTTP Client step</p></figcaption></figure>

{% hint style="info" %}
Based on the openweathermap API documentation:

• the URL calls the service to return the weather data based on:

${city}=London

${country}=GB

${units}=metric

${mode}=xml

• 'response' is return to the 'results' data stream field.

• the fields are 'mapped' in the fileds tab.
{% endhint %}

<figure><img src="/files/oXoUZHj5PQhuSg3vTBMC" alt=""><figcaption><p>map parameter fields to URL</p></figcaption></figure>
{% endtab %}

{% tab title="Get data from XML" %}
{% hint style="info" %}
This step provides the ability to read data from any type of XML file using XPath specifications.

For further details: [**Get data from XML**](/pentaho-data-integration/data-integration/data-sources/flat-files/xml.md)
{% endhint %}

1. Double-click on the step to view settings.

<figure><img src="/files/p9WKVCtPvNQDml6mQWbi" alt=""><figcaption><p>Get data from XML - defined in a field</p></figcaption></figure>

{% hint style="info" %}
The response from the API call - results - is the data source.
{% endhint %}

2. Click on the 'Content' tab.

<figure><img src="/files/vuzhZNQVQaaeuLZYzGZ4" alt=""><figcaption><p>Determine XPath</p></figcaption></figure>

{% hint style="info" %}
To determine the XPath, you will need to copy and paste a snippet of the API call.

The root is: /current
{% endhint %}

<figure><img src="/files/4MkXd5WKdhK9dXCExtjq" alt=""><figcaption></figcaption></figure>

3. Click on Fields tab.

<figure><img src="/files/phWpFXBPh3g0pKb2aa3J" alt=""><figcaption><p>Set the XPath / data Type to Nodes and attributes to retrieve the field values</p></figcaption></figure>
{% endtab %}

{% tab title="Row Normaliser" %}
{% hint style="info" %}
The Row Normaliser step converts the columns of an input stream into rows. You can use this step to normalize repeating groups of columns.
{% endhint %}

1. Double-click on the step to view settings.

<figure><img src="/files/ZkmTzlVeFyAPzkrQOHUo" alt=""><figcaption><p>Row Normaliser</p></figcaption></figure>
{% endtab %}

{% tab title="Select values" %}
{% hint style="info" %}
The Select values step can perform all the following actions on fields in the PDI data stream:

• Select values

• Remove values

• Rename values

• Change data types

• Configure length and precision of values
{% endhint %}

x

x

x
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="2. Data Access" %}
{% hint style="info" %}
Community Data Access (CDA) allows you to gather and combine data from several data sources into a single structure, which you can then use in dashboards. Driven by the need to unify access to the Pentaho data layer, CDA was developed to create an abstraction layer between a CTools dashboard and the physical connections to different databases.

CDA has three main objectives:

* Combine data from several sources
* Ensure security while accessing the data (avoiding, for instance, SQL injection problems)
* Ease data exports
  {% endhint %}

1. View the following CDA file.

\~/Workshop--Data-Integration/

```
<?xml version="1.0" encoding="UTF-8"?>
<CDADescriptor>
   <DataSources>
      <Connection id="weather" type="kettle.TransFromFile">
         <KtrFile>tr_weather_cda.ktr</KtrFile>
         <variables datarow-name="city"/>
         <variables datarow-name="country"/>
       </Connection>
   </DataSources>
   
   <DataAccess access="public" cache="true" cacheDuration="3600" connection="weather"
               id="current"
               type="kettle">
      <Columns/>
      <Parameters>
         <Parameter default="London" name="city" type="String"/>
         <Parameter default="GB" name="country" type="String"/>
      </Parameters>
      <Query>conditions_normalized</Query>
      <Output indexes="0,1"/>
   </DataAccess>
   
 </CDADescriptor>
```

x

x
{% endtab %}

{% tab title="3. Repository" %}

1. Define a connection to the 'Pentaho' Repository.

<figure><img src="/files/pOuxOpHs9J6aQlFRT9E8" alt="" width="375"><figcaption><p>Pentaho Repository</p></figcaption></figure>

2. Create a folder: Public / weather

x

x

x

x
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://academy.pentaho.com/pentaho-data-integration/use-cases/restful-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.