How do MKG API calls work?

For this guide, we assume that the MKG API is installed, the MKG Exchange license is acquired, an API key is created, and a user with the necessary rights is set up. For more information, visit the Getting Started.

Base URL

The base URL for the MKG API v3 is constructed as follows:

{{basisUrl}} = https://{{server}}:{{port}}/{{root}}

Example: https://mkgapi.domainname.nl:443/mkg

The server or domain name and the port where the MKG API is available can be requested within MKG. To do this, go to the Help icon (?) within MKG and then choose MKG API. Here, the API server name and API port number are listed.

The port is generally 443 or 8443, but this may vary for on-premise installations.

The root can be chosen for either the live environment or the training environment of MKG.

On-premise

Live environment: {{basisUrl}} = https://{{server}}:{{port}}/mkg
Training environment: {{basisUrl}} = https://{{server}}:{{port}}/mkgoefenclient

MKG Cloud

Live environment: {{basisUrl}} = https://saas*.mkg.eu:443/mkg
Training environment: {{basisUrl}} = https://saas*-oefen.mkg.eu:443/mkgoefenclient

Login

To log in with the MKG API, the following URL is required:

{{authUrl}} = {{basisUrl}}/static/auth

To log in, we use the following call:

POST {{authUrl}}/j_spring_security_check

Example URL: https://mkgapi.domainname.nl:443/mkg/static/auth/j_spring_security_check 

Headers:
Accept: application/json
Content-Type: application/x-www-form-urlencoded 

Body:
j_username:{{username}}
j_password:{{password}}

Upon a successful call (HTTP status code 200), a JSESSIONID will be returned in the response header.

Set-Cookie: "JSESSIONID=[...].mkg"

This JSESSIONID must be included in the header for every subsequent call as:

Cookie: "JSESSIONID=[...].mkg"

Session

Once logged in successfully, a session ID is returned. This session can be reused until it expires. Generally, a session expires 30 minutes after the last use. An expired session will result in an HTTP status code 401.

HTTP Status Codes

Call Construction

The URL for a call starts as follows:

{{restUrl}} = {{basisUrl}}web/v3/MKG

The endpoint can then be added to the restUrl.

{{restUrl}}/Documents/{{endpoint}}

A specific record of an endpoint can be requested by adding the primary key of the record after the endpoint.

{{restUrl}}/Documents/{{endpoint}}/{{Primary Key}}

When the primary key contains multiple fields, they are concatenated with the + sign. Alternatively, the RowKey of the specific record can be used instead of the primary key. The RowKey can only be requested via the API and is not known to the user or in the MKG Client.

{{restUrl}}/Documents/{{endpoint}}/{{RowKey}}

URL Percent-Encoding

Different rules apply to different parts of the URL.

Example URL:
https://{{server}}:{{port}}/mkg/web/v3/MKG/Documents/vorh/1+30240258?Fieldlist=vorh_num

path = /mkg/web/v3/MKG/Documents/vorh/1+30240258
query = Fieldlist=vorh_num

Path
When specifying a primary key for a specific record, only alphanumeric characters, spaces, hyphens, and underscores ( [a-z] [A-Z] [0-9] SPACE - _ ) may be used. The + sign is used to construct the primary key.

Query
For the query part of the URL, Percent-Encoding must be used, where a space must be translated to a %20.

The maximum length of the URL is 8000 characters after encoding.

Headers

For every call, the headers must include the session ID in the cookie. Additionally, X-CustomerID must be filled with the API key from MKG.

Cookie:  "JSESSIONID=[...].mkg"
X-CustomerID: {{APIKey}}
Accept: application/json
Content-Type: application/json

Example GET Call:

Example for retrieving sales order 30240258 from administration 1:

GET {{restUrl}}/Documents/vorh/1+30240258

Headers:

Cookie:  "JSESSIONID=1050E02F91B6EA25933ADDBE86B5B2955D7DF77FB53E.mkg"
X-CustomerID:  "ced6600c-e15a-eabd-8414-35844cd10b34"
Accept: application/json
Content-Type: application/json

Collections

From an endpoint, collections are sometimes available. With a collection, information can be retrieved from an underlying table that belongs to the endpoint.

GET {{restUrl}}Documents/{{endpoint}}/{{primary_key}}/{{verzameling}}

Example: From the Sales Orders endpoint (vorh), the API returns all lines linked to this sales order from the Sales Order Lines (vorr) through the collection vorh_vorr.

GET {{restUrl}}/Documents/vorh/1+30240258/vorh_vorr/

To select a specific line from the collection, the following call can be used:

GET {{restUrl}}Documents/{{endpoint}}/{{primary_key}}/{{verzameling}}/{{key}}

Example: From the Sales Orders endpoint (vorh), the API returns sales order line 2 from the Sales Order Lines (vorr) associated with the sales order through the collection vorh_vorr with the addition of the line number.

GET {{restUrl}}/Documents/vorh/1+30240258/vorh_vorr/2

Data Dictionary

Go to Data Dictionary in the MKG Client to find endpoints, fields, primary keys, collections, and services.

Data Types

In the Data Dictionary, the following data types (column: Type) can be found for the fields of an endpoint.

*In the data dictionary, more information can be found in the 'Format' column for the fields of an endpoint.

Retrieve Field Name in MKG

Within the MKG Client, you can retrieve a field name by standing in a field of a form and pressing  Ctrl+F11 .

Postman Collection

GET Call

A GET call is used to request data. It is possible to retrieve multiple records or a single specific record.

Parameters

Specific Record

A specific record of an endpoint can be requested by adding the primary key or RowKey of the record after the endpoint. In the Data Dictionary module in MKG, endpoints, fields, and also the primary key can be requested.

GET {{restUrl}}/Documents/{{endpoint}}/{{Primary Key}}

Example for retrieving sales order 30240258 from administration 1 with a number of fields:

GET {{restUrl}}/Documents/vorh/1+30240258?FieldList=vorh_num,debi_num,vorh_ref_onze,vorh_ref_uw,vorh_dat_levering

FieldList

With the FieldList parameter, the desired fields of the relevant endpoint are specified whose values need to be returned. If no FieldList is provided, it will only return the primary key fields.

It is possible to point to a field of another linked endpoint.

Example for pointing from the sales order (vorh) to the debtor (debi) to retrieve the debtor name:

GET {{restUrl}}/Documents/vorh/1+30240258?FieldList=vorh_num,debi_num,debi_num.debi_naam

Filter

With a filter, it is possible to request multiple records of an endpoint that meet a condition.

The following operators are possible when using the Filter parameter:

Functions when using the Filter parameter on a date field:

* Optionally, you can specify a plus or minus number. Example: sys_dat_aanm = Today(3) --> today plus 3 days.

Multiple filters can be linked using the operators AND and OR.

Example for retrieving sales order lines created in the last 30 days and not yet delivered:

GET {{restUrl}}/Documents/vorh?Filter=sys_dat_aanm >= Today(-30) AND vorr_leveren_afgewerkt = false

Pagination (NumRows & SkipRows)

In a GET call with more than 1000 results, only the first 1000 results will be shown. By using NumRows and SkipRows, the next 1000 records can be retrieved.

If no NumRows is provided, MKG will apply NumRows=100.

Example:

First 1000 records:

GET {{restUrl}}/Documents/rela?NumRows=1000&SkipRows=0

Next 1000 records:

GET {{restUrl}}/Documents/rela?NumRows=1000&SkipRows=1000

Next 1000 records:

GET {{restUrl}}/Documents/rela?NumRows=1000&SkipRows=2000

After the results, a suggestion call will be made for the next 1000 records or the previous 1000 records if more records are available:

GET {{restUrl}}/Documents/rela?NumRows=1000&SkipRows=2000

[...]

Sort

With the sorting parameter, a list sorting can be provided. 

GET {{restUrl}}/Documents/rela?Sort=rela_naam,-rela_num