Admin-IS / Admin-Consult API Werking voor de Softwareleverancier

Na opzet van de Admin-IS / Admin-Consult API kan je er mee aan de slag.
Onderstaande artikel is vooral bedoeld voor developers, die met de API aan de slag kunnen gaan.

Inhoudstafel

Link naar database

Data Filters

Paging

Link naar database

Van de accountant ontvangt u de URL + sleutel om de Consult API te kunnen gebruiken. De Swagger API bevindt zich op de "/doc" mapping. 

De eerste stap is een token ophalen met de gekregen sleutel. Met Swagger kan je dit ook testen:

Het resultaat is een geldig token (indien de sofware op actief gezet is).

Dit token is dus geldig tot TimeToLive. Wanneer dit vervallen is moet je een nieuw token aanvragen. Het token moet gebruikt worden in de andere API calls.

Data Filters

Het resultaat van een API kan gefilterd worden zodat er een beperkte set van data wordt teruggegeven.

Hier wordt de werking van de filters uitgelegd, deze technische werking is bewust in het Engels geschreven.

 With parameters, you can filter the result of an API for one or more values, even if those values contain spaces or special characters. The basic syntax is fairly straightforward; start with the API URL, add a question mark, and then add your filter syntax.
URL?Filter=Field eq 'value'

e.g. http://consultapi.syneton.be:2100/api/v1/customers?Filter=IsCompany eq 1

• Fieldnames and value are case in
• Fields must be part of the returned modelg. IsCompany is part of the Customer model.

Field types

Field type can be a number, date, boolean or string and the type used must match the type set in the model. For example, specifying a field of type "string" won't work if you're looking for a date or numeric value in a result column set as a date, such as InvoiceDate eq ‘John’.

• Stringsmust be enclosed with single quotes, as in 'manager name'.
• Numbersrequire no special formatting.
• Datesformat is ‘yyyy-mm-dd’ e.g. ?Filter=InvoiceDate gt ‘2020-01-01’
• Boolean 1(=True), 0 (=False)

Filter on a field

Let’s assume that the URL to our report is the following.

http://consultapi.syneton.be:2100/api/v1/customers

And we see in our result above that we have Dutch speaking customers. NL is the value that represents Dutch in the Language field of the Customer model. To filter the report to show data only for Dutch speaking customers, we append this string to the URL:

?Filter=Language eq 'NL'

So the url becomes:

http://consultapi.syneton.be:2100/api/v1/customers?Filter=Language eq 'NL'

Where Language and ‘NL’ are case insensitive.

Filter on more than one value in a field

To filter on more than one value in a single field, you use the in operator instead of the and operator. The syntax is:

?Filter=Field in ('value1', 'value2')

Using the same example, to filter the result to show data only for customers speaking French (‘FR’) or English (‘EN’) append the URL with the following;

?Filter=Language in ('FR', ‘EN’)

Operators

The API filter supports many operators in addition to 'and'. The table below lists those operators along with the content type they support.

Operator	Definition	Example
and	And	InvoiceAmount le 3000 and InvoiceAmount gt 1000
eq	Equals	City eq 'Bornem'
ne	not equal	City ne 'Bornem'
ge	greater than or equal	InvoiceAmount ge 1000
gt	greater than	InvoiceAmount gt 1000
le	less than or equal	InvoiceAmount le 1000
lt	less than	InvoiceAmount lt 1000
in	Including	Age in (27, 29)
Like ‘%...%’	Contains	Name like ‘%van%’
Like ‘X_Y’	Single character	Name like ‘P_L’

The Like operator can combine ‘%’ and ‘_’ as in standard SQL.

Paging

Een dataset wordt altijd in pagina's teruggegeven, met of zonder een filter (zie hierboven).

De technische details zijn bewust in het Engels uitgeschreven.

Every result will be returned in pages of default 20 records. The paging information is returned in the http header and can be used to create html hyperlinks:

<first> <prev> <next> <last>

<<    <     >     >>

The first request: http://consultapi.syneton.be:2100/api/v1/customers

http responde header link:

<http://consultapi.syneton.be:2100/api/v1/customers?page=2&per_page=20>; rel="next", <http://consultapi.syneton.be:2100/api/v1/customers?page=67&per_page=20>; rel="last", <http://consultapi.syneton.be:2100/api/v1/customers?page=1&per_page=20>; rel="first",

If you want the next page, use the rel="next" link being http://consultapi.syneton.be:2100/api/v1/customers?page=67&per_page=20

The new paging info in the http responde header:

link:

<http://consultapi.syneton.be:2100/api/v1/customers?page=1&per_page=20>; rel="prev", <http://consultapi.syneton.be:2100/api/v1/customers?page=3&per_page=20>; rel="next", <http://consultapi.syneton.be:2100/api/v1/customers?page=67&per_page=20>; rel="last", <http://consultapi.syneton.be:2100/api/v1/customers?page=1&per_page=20>; rel="first",

Notice the extra link "prev"

You can use any returned link or create you're own like 40 records per page: http://consultapi.syneton.be:2100/api/v1/customers?page=1&per_page=40 

The maximum record in one call is 100, requesting more will detault to 20 records.