@elastic.io/odata-library

odata-library

Contains methods to authenticate, make requests to OData APIs and build API entities json schema.

OdataClient

OdataClient class got most common methods for odata client

constructor(cfg, restClient, keys)

• cfg - configuration EIO component object.
• restClient - rest client to make requests with chosen auth type.
• keys - list of PKs for chosen entity type.

const restClient = new NoAuthRestClient(emitter, cfg);
const keys = [{
   name: 'id',
   required: false,
   type: 'Edm.Int64',
   wrapValueInQuotesInUrls: false,
}];
const odataClient = new ODataClient(cfg, restClient, keys);

async getMetadata()

Methods makes request with set rest client to 'baseUrl/$metadata' address and returns result as string

const result = await odataClient.getMetadata();

async getAll()

Methods makes request with set rest client to 'baseUrl/${this.cfg.objectType}'. Returns all object for provided object type. Be careful: this method DOES NOT support pagination.

const result = await odataClient.getAll();

async getObjectsPollingByDeltaLink(snapshot, objectType)

Method to make polling request to odata API. Uses deltaLink fetch that may not be supported.

• snapshot - snapshot EIO component object. snapshot object may contain deltaLink as string:
• objectType - object Type

{
   "deltaLink": "https://someDeltalink.com/with/details"
}

This method does NOT emitting snapshot by itself.

const result = await odataClient.getObjectsPollingByDeltaLink(snapshot);

async getObjectById(object, objectType)

Method get entities by PK value.

• object - object, which contains entity with PK values

• objectType - object Type For example:

• object has unique key id

const result = await odataClient.getObjectById(id, 'Customer');

• object has unique key No

const result = await odataClient.getObjectById({No: 3}, 'Customer');

async postObject(object, objectType)

Method makes POST request to insert entity.

• object - input object
• objectType - object Type

const result = await odataClient.postObject(object, 'Customer');

async putObject(object, objectType)

Method makes PUT request to update entity by PK.

• object - input object
• objectType - object Type

const result = await odataClient.putObject(object, 'Customer');

async patchObject(object, objectType)

Method makes PATCH request to update entity fields by PK.

• object - input object
• objectType- objectType - object Type

const result = await odataClient.patchObject(object, 'Customer');

async upsertObjectById(object, objectType, updateMethod = 'PATCH')

Method to upsert (update or, if not found, create) entity.

• object - input object
• objectType- objectType - object Type
• updateMethod - choosing method to make update with PATCH or PUT method. PATCH is default. Method will try to make update if PK provided with input object. If update will fail for some reason method would make POST request.

const result = await odataClient.upsertObjectById(object, 'Customer', 'PUT');

async deleteObjectById(object, objectType)

Method remove entities by PK value.

• object - object, which contains entity with PK values
• objectType- objectType - object Type

For example:

• object has unique key id

const result = await odataClient.deleteObjectById({id: 2}, 'Customer');

• object has unique key No

const result = await odataClient.deleteObjectById({No: 3}, 'Customer');

async deleteObjectsByCriteria(criteria, eTag, objectType)

Method remove entities by PK value.

• criteria - object, which contains entity with PK values
• eTag - current eTag of object
• objectType- objectType - object Type

const result = await odataClient.deleteObjectsByCriteria(criteria, eTag, 'Customer');

Authentication

Classes to make requests to restricted resources

NoAuthRestClient

NoAuthRestClient class to make rest requests no no auth APIs by provided options. Uses promisify(require('request')) library to make REST requests.

constructor(emitter, cfg)

• emitter - EIO emitting context.
• cfg - configuration of EIO component object.

const Client = new NoAuthRestClient(emitter, cfg);

async makeRequest(options)

Makes requests: options expects the following sub-variables:

• url: Url to call
• method: HTTP verb to use
• body: Body of the request, if applicable. Defaults to undefined.
• headers: Any HTTP headers to add to the request. Defaults to {}
• urlIsSegment: Whether to append to the base server url or
• if the provided URL is an absolute path. Defaults to true

BasicAuthRestClient

BasicAuthRestClient class extends NoAuthRestClient class. Makes requests to resource with basic auth.

constructor(emitter, cfg)

• cfg.username - mandatory cfg parameter contains username for authorization.
• cfg.password - mandatory cfg parameter contains password for authorization.

const Client = new BasicAuthRestClient(emitter, cfg, user, pass);

ApiKeyRestClient

ApiKeyRestClient class extends NoAuthRestClient class. Makes requests to resource with api key (custom header) auth.

constructor(emitter, cfg)

• cfg.apiKeyHeaderName - mandatory cfg parameter contains authorization header name.
• cfg.apiKeyHeaderValue - mandatory cfg parameter contains authorization header value.

const Client = new BasicAuthRestClient(emitter, cfg, user, pass);

OAuth2AuthorizationCodeRestClient

OAuth2RestClient class extends NoAuthRestClient class. Makes requests to resource with oauth2 access token auth.

constructor(emitter, cfg)

• cfg.oauth2 - mandatory cfg parameter contains oauth2 ids, config and tokens.

const Client = new OAuth2AuthorizationCodeRestClient(emitter, cfg);

This class can handle, refresh and emit oauth2 EIO configuration.

Metadata generation

Classes and methods to generate json schemas and EIO io metadata

MetadataBuilder

MetadataBuilder class can generate EIO io metadata for most common actions and triggers. Requires CsdlConverter class to process csdl. All fields except PKs is not required in input metadata.

constructor(csdlConverter, referenceResolveLevel)

• csdlConverter - CsdlConverter class to process csdl.
• referenceResolveLevel - csdl processing option for CsdlConverter resolveMetadataRefs(jsonSchema, maxLevel) method

const converter = await new CsdlConverter(inputCsdl).build();
const metadataBuilder = new MetadataBuilder(converter, 10);

getObjectsNamingList()

Method returns resource list can be used in EIO getObjects method as action resource map.

const result = metadataBuilder.getObjectsNamingList();

getTriggerMetadata(objectType)

Method returns get metadata for chosen objectType for polling trigger. Has no 'in' metadata, PK is required for output.

const result = metadataBuilder.getTriggerMetadata('Entity');

getByIdMetadata(objectType)

Method returns metadata by chosen objectType for 'getById' action. 'in' metadata has required PK only.

const result = metadataBuilder.getByIdMetadata('Entity');

getPostMetadata(objectType)

Method returns metadata by chosen objectType for POST action. 'in' metadata has required PK.

const result = metadataBuilder.getPostMetadata('Entity');

getPutMetadata(objectType)

Method returns metadata by chosen objectType for PUT action. 'in' metadata not expected PK.

const result = metadataBuilder.getPutMetadata('Entity');

getUpsertMetadata(objectType)

Method returns metadata by chosen objectType for upsert action. 'in' metadata expected but not required PK.

const result = metadataBuilder.getUpsertMetadata('Entity');

getDeleteMetadata(objectType)

Method returns metadata by chosen objectType for DELETE action. 'in' and 'out' metadata contains required PK only.

const result = metadataBuilder.getDeleteMetadata('Entity');

CsdlConverter

CsdlConverter lass can process OData csdl by input string or resource url

async build()

CsdlConverter class builder Can be used in 2 ways:

• await new CsdlConverter(inputCsdl).build(); - to build converter by input csdl string
• await new CsdlConverter().buildByMetadataUrl('https://example.net/$metadata'); - to build converter by data from csdl resource

getResourcesList()

Method to get list of entities can be used as resources in component with their primary keys description:

const converter = await new CsdlConverter(inputCsdl).build();
const result = converter.getResourcesList();

Result sample:

[
  {
    "name": "Products",
    "keys": [
      {
        "required": true,
        "name": "ID",
        "wrapValueInQuotesInUrls": false,
        "type": "Edm.Int32"
      }
    ]
  }
  ...
]

convertCsdlString(entityName)

Method to get object contains raw json schema (with unresolved $ref(s)) and PKs list for chosen entity. Throws an error if no such entity name in json schema or found more than one entity with same name.

const converter = await new CsdlConverter(inputCsdl).build();
const result = converter.convertCsdlString('Entity');

resolveMetadataRefs(jsonSchema, maxLevel)

Method resolve all refs in provided json schema.

• jsonSchema - input json schema
• maxLevel - unrequired parameter to set max ref depth resolving - 3 by default. Method are ignoring ref if it was resolved on higher recursion level to prevent dead cycle. !!! Be careful - this method can generate REALLY big output schema.

const converter = await new CsdlConverter(inputCsdl).build();
const result = converter.convertCsdlString('Entity');
const jsonSchema = converter.resolveMetadataRefs(result.jsonSchema, 8);