@daradermody/web-service-interface v0.2.5

= Developing a Web Service Driver

This package provides an interface for developing plugins used for extending web services in Siren Investigate. These plugins are called web service drivers and are adapters for external APIs or functionality. Siren Investigate then uses these web service drivers to get data from these external APIs. Depending on invocation type, this data may also be stored in Elasticsearch.

Conceptually, a web service driver provides access to a service group, which is a grouping of one or more functions called services. These functions are the different endpoints that a single vendor might expose. For example, a service group called Google might consist of WebSearch, ImageSearch, and NewsSearch services.

TIP

To get started immediately, try our https://www.npmjs.com/package/@sirensolutions/generator-web-service[generator package] to create a new service driver.

====

To develop a web service driver, add this package as a dependency:

source,bash

npm install @sirensolutions/web-service-interface

This package is written in Typescript and contains interfaces and functions for building and registering web services. Once this dependency is added, created a class that implements the ServiceDefinition interface. This interface ensures that your service class provides all the properties and functions required by Investigate. Specifically, the properties required are:

• name: The unique name of the service
• inputSchema: The input parameters that the service accepts when queried (see <<input-schema,Input Schema>>)
• outputConfiguration: The outputs returned when queried (see <<output-configuration,Output Configuration>>)

The class must also provide the invoke function, which is called when the service is queried. This function is given the parameters defined in the service's inputSchema property, and must return a list of results containing properties defined in the service's outputConfiguration property.

source,typescript

// MyService.ts import { InputSchema, OutputConfiguration, ServiceDefinition, SimpleMap } from '@sirensolutions/web-service-interface';

export default class MyService extends ServiceDefinition { readonly name = 'my-service'; readonly inputSchema: InputSchema = { input: { type: 'text' } }; readonly outputConfiguration: OutputConfiguration = { output: 'text' };

async invoke(params: { input: string }): Promise<SimpleMap[]> { // Query external API and return list of the results in the form of { output: 'response' } }

}

Once the service is defined, you register it on startup by calling the registerServices function in the index.ts.

source,typescript

// index.ts import { registerServices } from '@sirensolutions/web-service-interface'; import MyService from './MyService';

export = registerServices('my-service-group', MyService);

The parameters of registerServices are as follows:

• Service group name: Name of the group that groups the services together in the UI
• List of web services: A list of classes that implement the ServiceDefinition abstract base class
• Optional configuration schema: Used if the service group needs additional configuration (see <<service-configuration,Service Configuration>>)