Providing API’s (Application programming interface)

Warning This file is maintained at conductions google drive, please make any suggestions of alterations there.

The gateway provides an API for other applications to use and consumes API’s from sources in that way the gateway acts both as an provider and consumer of API’s. How to consume API’s from the gateway is further detailed under the Sources chapters. This chapter deals with providing API’s from the gateway to other applications

Endpoints

API’s are generated by endpoints, you can read more about setting up endpoints here.

Creating Applications

Users, Processes and Applications

From a logging perspective the gateway differs any call on the aspects - Who is making the call? e.g. User John - How is he making the call? e.g. from the front desk applications - For which process is he making the call? e.g. client registration

While it isn’t necessary to alway use all of the above settings it is het preferred way of setup

Querying the API

A normal filter: {propertyName}={searchValue} e.g. firstname=john

A property is IN array filter: {propertyName}[]={searchValue1} e.g. ‘firstname[]=john’ {propertyName}[]={searchValue2} e.g. ‘firstname[]=harry’

or

A normal filter with method: {propertyNema}[method]={searchValue} e.g. ‘firstname[case_insensitive]=john’

A property is IN array filter with method: {propertyNema}[method][]={searchValue1} e.g. ‘number[int_compare][]=2’ {propertyNema}[method][]={searchValue2} e.g. ‘number[int_compare][]=5’ Note that not every method can be used like this

All functional query parameters always start with an _ to prevent collisions with property names e.g. _order

Methods

method less queries (e.g. firstname=john) are treated as exact methods firstname[exact]=john

[exact] (default) exact match Only usable on properties of the type text, integer or datetime. Seea

[case_insensitive] (default) case insensitive searching Only usable on properties of the type text, uses the regex function under the hoot in an case insensitive way.

[case_sensitive] case sensitive searching Only usable on properties of the type text, uses the regex function under the hoot in an case sensitive way.

[like] wildcard search Only usable on properties of the type text, integer or datetime, works the same as a regex search but wraps the value in / creating /$value/ and sets the matchings pattern to case insensitive.

[>=] equal or greater than Only usable on properties of the type integer, will automatically cast the searched value to integer to make the compereson

[>] greater than Only usable on properties of the type integer, will automatically cast the searched value to integer to make the comparison

[<=] equal or smaller than Only usable on properties of the type integer, will automatically cast the searched value to integer to make the comparison

[<] smaller than Only usable on properties of the type integer, will automatically cast the searched value to integer to make the comparison

[after] equal or greater than Only usable on properties of the type date or datetime

[strictly_after] greater than Only usable on properties of the type date or datetime

[before] equal or smaller than Only usable on properties of the type date or datetime

[strictly_before] smaller than Only usable on properties of the type date or datetime

[regex] compare the values based on regex Only usable on properties of the type string

[int_compare] will cast the value of your filter to an integer before we filter with it. Useful when the stored value in the gateway cache is an integer but by default you are searching in your query with a string “1012”. Works with the property IN array filter like this: {propertyNema}[int_compare][]={searchValue1}

[bool_compare] will cast the value of your filter to a boolean before we filter with it. Useful when the stored value in the gateway cache is a boolean but by default you are searching in your query with a string “true”. Works with the property IN array filter like this: {propertyNema}[bool_compare][]={searchValue1}

Note When comparing dates we use the php dateTime($value) function to cast the strings to dates. That means that you can also inputs strings like now.yesterday see the full list of relative formats.

Ordering the results

_order[propertyName] = desc/asc

Note The _searchorder property currently also supports order for backwards compatibility

Working with pagination

Requests to collections (e.g. more then one object) are encapsulated in an responce object, the gateway automatically paginates results on 30, you can however set your own amount of items per pages trough the _limit query parameter. There is no upper limit to this parameter so if desired you could request 10000 objects in one go. This does however come with a performance drain because of the size of the returned response in bytes where the main throttle is the internet connection speed of the transfer combined with the size of individual objects. We therefore suggest not to user limits greater then 100 in frontend applications.

{
 “total“:100,
 “limit”:30,
 “pages”:4,
  “page”:1,
 “results”:[]
}

_limit _page _start

Note The pagination properties currently also supports for backwards compatibility by removing the _ part. Meaning that they may also be used as limit,page and start

The search index

The common gateway automatically creates a search index of all objects bassed on the text value of their properties (non-text values) are ignored. This search index can be used when approaching api endpoints. through the special _search query parameter. Search functions as a wildcard.

e.g. _search=keyword

By default the search query searches in all fields, if you want to search specific properties you can do so by defining them as methods. You can search properties fields (in an OR configuration) by separating them trough an , and supplying them in the method you can also search in sub properties e.g. _search[property1,property2.subProperty]=keyword.

Note The _search property currently also supports search for backwards compatibility

Limiting the return data

In some cases you either don’t need or don’t want a complete object. In those cases it's good practice for the consuming application to limit the field it wants in its return call. This makes the return messages smaller (and therefore faster) but it is also more secure because it prevents the sending and retention of unnecessary data.

The returned data can be limited using the _fields query parameter, this parameter is expected to be an array containing the name of the properties that are requested. It is possible to include nested properties using dot notation. Let’s take a look at the following example. We have a person object containing the following data:

{   
     “firstname”:”John”,
     “lastname”:”Do”,
    “born”:{
        “city”:“Amsterdam”,
        “country”:”Netherlands”,
”date”:”1985-07-27” 
    }
}

Of we then query using _fields[]=firstname&_fields[]=born.date we would expect the following object to be returned:

{   
     “firstname”:”John”,
    “born”:{
”date”:”1985-07-27” 
    }
}

Note The _fields property may be aliased as _properties

_remove is specifieke unset

Specifying the data format

The gateway can deliver data from its data layer in several formats, those formats are independent from their original source. e.g. A source where the gateway consumes information from might be XML based but the gateway could then provide that information in JSON format to a different application.

The data format is defined by the application requesting the data through the Accept header.