API Reference

Service Definition

The ServiceDefinition interface describes the properties on a web service class. This includes properties that the developer class must provide as well as properties provided during runtime.

Property Type Description

config

{ [key: string]: JoiSchema }

The configuration provided in the Investigate configuration file. This property is automatically set during runtime and is not required in the class that implements the ServiceDefinition interface.

name

string

The name of the web service. The name must be unique within the web service group.

inputSchema

InputSchema

The definition of input parameters that this web service accepts.

outputConfiguration

OutputConfiguration | undefined

A definition of the output structure of the web service driver. If you set this to undefined, the response structure is unrestricted but not stored in Elasticsearch.

keepInvocationHistory

boolean

Store invocation metadata, such as timestamp, user, or inputs in Elasticsearch. This is only applicable when the output of the web service is variable (outputConfiguration is undefined), because metadata is always stored for normal web services.

invoke

async (params: Map) ⇒ Map[] | { [indexSuffix: string]: Map[] }

The function that is called when the web service is queried. This function is given the parameters as defined in the inputSchema property, and must return results as defined in the outputConfiguration property.

Example

// 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' }
  }
}

Registering Web services

When registering web services we use the registerServices(…​) function. This will register a web service(s) to a web service group.

Parameter

Type

Description

Default

serviceGroup

string

The name of the group that groups the services together in the UI.

Services

ServiceDefinitionClass[]

A list of classes that implement the ServiceDefinition abstract base class descibed here

config

ConfigSchema

(Optional) Used if the web service group needs additional configuration. For more, see Service Configuration

{}

Example

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

const  requiredConfig = { auth_token: Joi.string().required() };
export = registerServices('my-service-group', [MyService], requiredConfig);

Input Schema

The input schema is where you specify the input parameters to the web service. This consists of specifying the type and whether or not it is required. These parameters are passed into your invoke method. Validating that the input parameters match the input schema is automatically done before the invoke method is called.

Name

Type

Description

Default

type

string

The Elasticsearch field data type which is associated to the property.

Valid types:

'text' | 'keyword' | 'date' | 'long' | 'float' | 'boolean' | 'ip' | 'geo_point' | 'any'

required

boolean

Specifies if the property is mandatory: must not be null, undefined etc.

false

description

string

Describes the property

''

Values for the any type can be any serializable value, for example an object, an array, or any of the other field types. It is serialised into a string when stored as part of the invocation metadata in Elasticsearch. The Web Services dashboard represents it as a string field, but any value can be used when using the Siren scripting API to invoke the web service.

Example

readonly inputSchema: InputSchema = {
  query: {
    type: 'text',
    required: true
  },
  language: {
    type: 'keyword',
    description: 'text' // 'required' defaults to false
  }
};

invoke(params: object): Promise<SimpleMap> {
  // params will be either { query: 'foo' } or { query: 'foo', language: 'bar' }
}

Output Configuration

This declares the structure of the data from a web service driver. It can be one of the following:

  • a single-level object with key: 'type' pairs, or

  • a complex object, in which the top-level keys determine the index that the result is stored in

  • undefined

See Output Configuration for more information about how data is stored in Elasticsearch.

Name

Type

Description

OutputConfiguration

{ [key: string]: {} | string }

The Output configuration defines the structure of the returned data and where it is stored. See examples below

Example

// Simple output configuration
readonly outputConfiguration: OutputConfiguration = {
  url: 'text'
}

/**
 * Complex output configuration
 * This could contain n amount of key value pairs
 * as well as k depth of nested objects.
 */
readonly outputConfiguration: OutputConfiguration = {
  'index-prefix': {
    bar: {
      buzz: 'text'
    },
    fizz: 'text'
  }
}

The above implies that the web service returns a list of objects under the index-prefix key, for example:

return {
  'index-prefix': [
    {
      bar: {
        buzz: 'value1'
      },
      fizz: 'value2'
    }
  ]
}

This list of documents will then be stored in web-service-mygroup-mywebservice-results-index-prefix.