Advanced tutorial: Using the generator package to create Web service drivers

In this tutorial, you will use the Siren generator package to set up the project. You will use OpenWeatherMap API for HTTP requests.

Prerequisites

Before you begin, it is recommended that you complete both the Beginners' tutorial and the Intermediate tutorial.

Download and install the following tools:

Node.JS v10.19
An editor of your choice, such as VS Code or Webstorm
Siren Platform
OpenWeatherMap API key. Get an API key for OpenWeatherMap, by creating an account and navigating to the API keys section.

The Siren generator package is written in Typescript and contains interfaces and functions for building and registering Web services. For more information, see the Typescript website.

Steps

You can generate a boilerplate Web service driver project by using a template that is provided in the Siren generator.

Install the generator by running the following command:

 npm install -g yo @sirensolutions/generator-web-service

Generate the project by running the following command:
```
yo @sirensolutions/web-service
```
The generator asks you to enter the name of the service group and the Web service. Name the service group generator-tutorial and the Web service MyGeneratedService.
```
cd generator-tutorial/
ls
```
The generator downloads all necessary dependencies and generates the src/ directory, which contains the Typescript files.

Open the project and check that the structure appears as follows:

generator-tutorial/
├─ node_modules/
├─ src/
│   ├─ index.ts
│   └─ MyGeneratedService.ts
├─ gulpfile.js
├─ package.json
├─ README.md
├─ tsconfig.json
└─ package-lock.json
└─ invoke

Install the moment package by running the following command:
```
npm i moment
```

Modify the src/MyGeneratedService.ts file. Import the moment package and declare the auth_token to the class declaration:

import * as moment from 'moment';

export default class MyGeneratedService extends ServiceDefinition<{ auth_token: string }> {
// ...
}

Change the inputSchema. This requires that you specify the city_name attribute. You can also specify the use_metric_system attribute (optional):

  readonly inputSchema: InputSchema = {
    city_name: {
      type: 'text',
      description: 'The name of the city to query',
      required: true
    },
    use_metric_system: {
      type: 'boolean',
      description: 'Toggle between the metric / imperial system'
    }
  };

Change the output configuration. This describes the structure of the returned data and indicates that the data is to be stored in a dedicated index - in this case, named web-services-generator-tutorial-mygeneratedservice-results-weather.

  readonly outputConfiguration: OutputConfiguration = {
    weather: {
      time_stamp: "date",
      location: "geo_point",
      description: "text",
      temperature: "float",
      feels_like: "float",
      humidity: "float",
      name: "keyword",
    }
  };

Finally, change the invoke function as follows:

   async invoke(inputs: { city_name: string, use_metric_system?: boolean }): Promise<DataIndexResults> {
    inputs.use_metric_system = inputs.use_metric_system || false;
    const options = {
      params: {
        q: inputs.city_name,
        units: inputs.use_metric_system ? 'metric' : 'imperial',
        appid: this.config.auth_token
      },
      headers: {
        'Content-Type': 'application/json'
      }
    }
    const response = await axios.get('https://api.openweathermap.org/data/2.5/weather', options)
      .catch(err => Promise.reject(err.response && err.response.status < 500 ? new WebServiceError(err.response.data) : err));
    return {
      weather: [{
        time_stamp: moment().toISOString(),
        location: response.data.coord,
        description: response.data.weather.description,
        temperature: response.data.main.temp,
        feels_like: response.data.main.feels_like,
        humidity: response.data.main.humidity,
        name: response.data.name
      }]
    };
  }

Test the invoke function by running the following command:
```
node invoke mygeneratedservice --input:city_name London --config:auth_token <your-api-key>
```
The params.appid in the invoke function uses this.config.auth_token.
Before you install the Web service in Siren Investigate, add the following code to the config/investigate.yml file:
```
web_services:
  generator-tutorial:
    config:
      auth_token: '<your-API-key>'
```
It’s ready to go! Package the project by running the following command:
```
npm run package
```
This command creates the target/generator-tutorial.zip file.

Install the Web service driver by running the following command:

cd path/to/siren-investigate
./bin/investigate-plugin install file:///absolute/path/to/generator-tutorial/target/generator-tutorial.zip

Start Elasticsearch and Siren Investigate by running the following commands:

cd path/to/elasticsearch
./bin/elasticsearch

cd path/to/siren-investigate
./bin/investigate

To start using the service, copy and paste localhost:5606 into your browser.

For more information about creating Web services, see API reference.