# Flo.w Client Library

# Introduction

The Flo.w Client Library is a JavaScript/TypeScript library used by Flo.w developers to simplify making requests to the Flo.w Engine REST API. The library is 'isomorphic', meaning that it can be used in both client-side web applications and server-side Node.js services.

The Client Library matches the structure of the REST API but adds Typescript type information and dispatching of HTTP requests to simplify the task of the developer. Use of the library provides code completion and hinting in many code editors and IDEs.

# Prerequisites

We recommend using a Node version manager to install Node.js and NPM:

nvm (opens new window) for Mac and Linux.
nvm-windows (opens new window) for Windows.

# Installation

The Client Library is designed to be installed as a project dependency and is available from NPM (opens new window).

To install the library and add it as a dependency in you project's package.json file, issue the following command.

# Install flow-engine-client as a project dependency.
npm install flow-engine-client

# Usage

To instantiate an instance of the client:

import { Client } from 'flow-engine-client';

const host = 'https://flow.emu-analytics.com'; // Flo.w Engine host URL
const apiKey = 'b6b77cc4-904a-46d1-aa0f-3bf3848ce4c7'; // Flo.w API key

const client = new Client(host, apiKey);

The instantiated client provides a collection of endpoints that match the Rest API endpoints described in the REST API reference documentation. Calling a method on an endpoint will issue a REST API request and return the results as a Promise. REST API options are provided as arguments to the method.

Client Endpoint Property	Description
`client.auth`	Authentication methods
`client.auth.users`	User methods
`client.apiKeys`	API key methods
`client.applications`	Application methods
`client.appconfig`	Application configuration methods
`client.databases`	Database methods
`client.datasets`	Dataset methods
`client.styles`	Map style methods
`client.tileSources`	Map tile source methods
`client.uploads`	Map upload methods and data upload capability
`client.tiles`	Map Server tile methods
`client.maps`	Map Server base map methods

Authentication

The API key set when the client instance is created is sent with each request. The API key must confer appropriate permissions for a request to succeed. Unauthorized requests are signalled by rejecting the returned promise.

Flo.w RDF

An instance of the Flo.w Client Library is also available from the Flo.w RDF context object. See Flo.w RDF.

# CRUD operations

Most endpoints provide standard CRUD methods (create/read/update/delete) that map to Flo.w REST API CRUD operations. CRUD methods can take an optional params argument that is appended to the query string of the resulting REST API URL. This can be used to supply options such as limit, offset, filter etc. See the REST API documentation for options supported by CRUD operations.

Operation	Method Signature
Create	`create(data: Partial<T>, params: Record<string, any> = {}): Promise<T>`
List	`list(params: Record<string, any> = {}): Promise<T[]>`
Get	`get(id: string, params: Record<string, any> = {}): Promise<T>`
Update	`update(id: string, data: Partial<T>, params: Record<string, any> = {}): Promise<T>`
Delete	`delete(id: string, params: Record<string, any> = {})`

An example query:

// Retrieve a list of 5 datasets.
const results = await client.datasets.list({limit: 5});

The resulting REST API request:

GET /api/v1/datasets?limit=5 HTTP/1.1
Host: flow.emu-analytics.net
Content-Type: application/json
x-api-key: f7748763-e75f-4a79-a40a-92148855da49

# Querying Flo.w Datasets

To query a Flo.w Dataset call the query method of the datasets client endpoint. See Dataset Queries for full information on how to specify a query.

The Flo.w Client Library uses the 'advanced' query syntax resulting in a POST request to the REST API query operation. The query method signature is shown below:

client.datasets.query(
  datasetId: string,   // Dataset ID
  query: DatasetQuery, // Dataset query definition
  params: {}           // Additional parameters added to query string of request
)

The second argument (query) is sent as the request body. The third argument (params) is added to the request query string.

Querying parameterized datasets

To supply parameters when querying parameterized Flo.w Datasets, specify them in the third params argument.

An example query:

// Query the 'airquality' dataset for features where 'name' is like 'Ba%'.
// Limit to 1 result and return results as a GeoJSON feature collection.
const results = await client.datasets.query('airquality',
  {where: {name: {$like: 'Ba%'}}, limit: 1},
  {format: 'geojson'});

console.log(results);

/* Output:
Object {
  type: "FeatureCollection"
  features: Array(1) [
    0: Object {type: "Feature", geometry: Object, properties: Object}
  ]
}
*/

The resulting REST API request:

POST /api/v1/datasets/airquality/query?format=geojson HTTP/1.1
Host: flow.emu-analytics.net
Content-Type: application/json
x-api-key: f7748763-e75f-4a79-a40a-92148855da49

{"where": {"name": {"$like": "Ba%"}}, "limit": 1}

# Token-Based Authentication

To authenticate REST requests using a user-based bearer token rather than a Flo.w API key, set the accessToken property of the client instance to the JWT bearer token. The token will be sent in the Authorization header of subsequent requests (as Authorization: bearer <token>). Set the accessToken to null to revert to API key-based authentication. See Authentication for a full description of how token-based authentication works.

# Overriding the API Key

To override the configured API key or accessToken for an individual request specify the apiKey parameter using the params argument of request methods. For example, to query a dataset associated with another Flo.w application:

client.datasets.query(
  datasetId: 'dataset1',
  query: {...},
  params: {
    apiKey: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  }}
)

← Flo.w CLI Flo.w REST API Reference →