API Definition – byNeuron

What is it?

API Definitions allow one to specify a query API, it's possible query parameters and how the result should be returned into a simple JSON format.

How to use it?

An API Definition can be requested using the API request Task via REST or Camunda. To request an API Definition one needs to provide the API Definitions externalId and the specified query parameters.

example of how to use an API Definition via rest:

POST https://app3.dev.byneuron.com/task-backend/tasks/inni/api/request
headers: (minimal required)
X-TENANT-ID: TENANT1 -> the name of the tenant
Authorization: Bearer xxxx

body:
{ 
	"apiDefinitionExternalId": "DEAL_BY_ID",  -> the name of the API Definition
	"queryParameters": {  -> the query parameters
		"id": "000001"
  } 
}

Example use cases

simple data retrieval for BI & Reporting

retrieve data which is necessary for decisions in a process

custom 'query' API's for external applications

API Definition structure

General:

The externalId of the API Definition will be used when making the request

The Active field allows you to activate/de-activate the API Definition

The Version of the API definition can be provided, currently not used yet for requesting the API definition.

Configuration blocks:

Data - parameters:

queryParameters: parameters that can be used to query entities

headerParameters: currently 2 parameters (userId and TenantId) can be automatically retrieved from the headers/JWT and used in the Query. To use one of these parameters, add them to the queryParameters.

{
	"queryParameters": [
		  { "name": "userId", "type": "string" }, -> will make the user id in the header Bearer Token available as variable ${userId}
      { "name": "tenantId", "type": "string" } -> will make the header X-Tenant-ID available as variable ${tenantId}
  ]
}

timelineParameters: parameters required to aggregate event data of selected items

Query

The query will will be executed. In the query, the query parameters can be referenced with the notation: ${<queryParameterName>}

Use in your Transform part the timelineParameter <name>: id to replace this part with the request aggregated events of the item with id <id>.

This query is written in nuQL graph query language.

Testing tool can be found in the ADMIN PORTAL > Data > Query (Tab: NUQL Query)

Transform

Remark: If the Transform field is explicitly not used, put nothing in it!

In this field the transform logic to compile the JSON result can be provided. The transform logic uses the query output as input and will execute sub queries for events when needed.

Testing tool can be found in the ADMIN PORTAL > Data > Query (Tab: NUQL Transform)

Name	Type	Description	Validation
name	Text	Specifies the name of the API Definition
externalId	Text	Specifies the external id of the API Definition, used when requesting the data
version	Text	Specifies a version, manually set
data	JSON	Specifies the query- and/or timeline parameters for the API definition	When provided query parameters need to match the query parameter variables in the query itself
query	Text	Specifies query in nuQL, variables can be used with ${ } syntax	Not possible to use variables which are not defined in data field
transform	Text	Specifies transformation logic in nuQL/transform	When timeline parameters are provided, a timeline query is done when using the same name in transformation logic

Example API definition

Data

{
  "queryParameters": [
    {
      "name": "contractPublicId",
      "type": "string"
    },
    {
      "name": "tenantId",
      "type": "string"
    }
  ]
}

Query

InniTenant:?tenant entity:key ${tenantId}; link:isAssignedTo IndexSet:?is. 
Agreement:?agreement link:isDefinedIn ?is; attribute:publicId ${contractPublicId}; link:hasPart AgreementProduct:?cp. 
AgreementProduct:?cp link:isDefinedIn ?is; link:hasFeature Arrangement:?arrangements. 
Arrangement:?arrangements attribute:active true; link:isDefinedIn ?is; link:isImplementationOf ProductArrangement:?productArrangements. 
AccessPointArrangementRelation:?apArrangements link:isDefinedIn ?is; link:hasTarget ?arrangements; link:hasSource AccessPoint:?accessPoint.

Transform

{ accessPoints: result(?accessPoint) { externalId, publicId, id, accessPointType } }