@genability/api v3.2.1

Genability Javascript SDK

This SDK enables faster integration of the Genability APIs into your Node.js, React, Angular, Web Browser and other Javascript compatible applications.

Table of Contents

0. Genability API credentials
1. Basic web front end use
2. Basic npm usage
3. NodeJS backend proxy example
4. Maven Plugin for NodeJS
5. API usage

Genability API Credentials

If you don't have one already, you'll need a Genability account, as well an App ID and App Key, before you get started.

Integrations

Basic web front end use:

Include the library with a script tag:

<script src="/@genability/api/dist/main.js"></script>

Instantiate Genability API Client

For frontend use, the API client will send requests to the url specified in the proxy option. Your backend proxy must provide Genability API credentials and forward the request to https://api.genability.com. Do not include your Genability API credentials in user-facing frontend code.

const GenAPIClient = Genability.Client.configure({ proxy: '/genability-api' });

Instantiate a request object

const territoriesRequest = new Genability.restApis.GetTerritoriesRequest();
territoriesRequest.masterTariffId = '522';

Call the API method

GenAPIClient.territories.getTerritories(territoriesRequest);

Basic npm usage

Prerequisites: Node.js (^10.12.0, or >=12.0.0) built with SSL support. (If you are using an official Node.js distribution, SSL is always built in.)

You can install genability sdk using npm:

$ npm install @genability/api --save

Import Genability API client

import { Genability } from '@genability/api';

Instantiate Genability API Client

For frontend use, you must specify a proxy url and provide credentials on the backend..

For backend use in node or other environments, you can provide Genability API credentials to the client in several ways. The client will search for credentials in the following order:

1. Credentials explicitly provided to the API client
2. Credentials stored as environment variables GEN_APP_ID and GEN_APP_KEY
3. Credentials stored in a credentials.json file in the .genability folder in the user's home directory, in this format:

{
  "profileName" : {
    "appId":"", // Your Genability appId,
    "appKey":"" // Your Genability appKey
  }
}

If the API client doesn't find credentials in any of these places, the request will be sent without any credentials.

Instantiate a client, and optionally provide credentials, like this:

const GenAPIClient = Genability.Client.configure({
  profileName: '',// Optionally specify a profile name to use from your 
                  // ~/.genability/credentials.js file
  credentials: {  // Optionally provide credentials explicitly
    appId: '',    // Your Genability App ID
    appKey: '',   // Your Genability App Key
    jwtToken: '', // A JWT token — this can be used to authenticate  requests to a serverless proxy function
    proxyReq: '', // A function used to create an Axios request interceptor for all requests created by 
                  // the API, should requests to a proxy function need to be modified
  }
});

The credentials option also accepts a function which returns an object with the above properties.

Instantiate a request object

import { restApis } from '@genability/api';
const territoriesRequest = new restApis.GetTerritoriesRequest();
territoriesRequest.masterTariffId = '522';

Call the API method

Genability.territories.getTerritories(territoriesRequest);

NodeJS backend proxy example

Include http-proxy-middleware in package.json

Instantiate proxy middleware

const createProxyMiddleware = require('http-proxy-middleware').createProxyMiddleware;

Create ExpressJS Route

const genabilityAuthString = Buffer.from(`yourGenabilityAppId:yourGenabilityAppKey}`).toString('base64');

app.use('/genability-api', createProxyMiddleware({
    target: 'https://api.genability.com',
    changeOrigin: true,
    onProxyReq: function (proxyReq) {
        proxyReq.setHeader('Authorization', 'Basic ' + genabilityAuthString);
    },
    pathRewrite: {
        '^/genability-api': '/',
    },
}));

Maven Plugin for NodeJS

A useful way to use the Genability Javascript SDK in a project with a Java backend is to include the frontend-maven-plugin. This plugin will install NodeJS and NPM and enable running npm install on every build of the Java project.

Include frontend-maven-plugin in pom.xml

<plugin>
    <groupId>com.github.eirslett</groupId>
    <artifactId>frontend-maven-plugin</artifactId>
    <version>1.10.0</version>
    
    <configuration>
      <workingDirectory>src/main/webapp</workingDirectory>
    </configuration>
    
    <executions>
      <execution>
        <id>install node and npm</id>
        <goals>
          <goal>install-node-and-npm</goal>
        </goals>
        <configuration>
          <!-- See https://nodejs.org/en/download/ for latest node and npm (lts) versions -->
          <nodeVersion>v12.18.0</nodeVersion>
          <npmVersion>6.14.4</npmVersion>
        </configuration>
      </execution>
    
      <execution>
        <id>npm install</id>
        <goals>
          <goal>npm</goal>
        </goals>
        <!-- Optional configuration which provides for running any npm command -->
        <configuration>
          <arguments>install</arguments>
        </configuration>
      </execution>
    </executions>
</plugin>

Include package.json

Given the example above you would create your package.json in src/main/webapp.

Map node_modules to static route

The node_modules then need to be mapped to a static file path in your web server. Here is an example mapping using the Spring framework:

<mvc:resources mapping="/static/**" location="/node_modules/" />

The packages in your node_modules will then be available to you in your front end Javascript in the /static path.

API usage