Getting started

Introduction to the MKG API

With the MKG API, it is possible to connect external programs or software to MKG. This article explains how the MKG API works, what you can use it for, and what support you can expect. Read more

Calls

To test the calls below, we recommend using the API platform Postman.

1. API Login

This call allows you to log in to the MKG API. In case of a successful login (HTTP status 200), the call returns a cookie with a JSESSIONID. This must be included in the header of subsequent calls.

POST {{protocol}}://{{server}}:{{poort}}/mkg/static/auth/j_spring_security_check

Headers

• Content-Type = application/x-www-form-urlencoded
• Accept = application/json

Body (x-www-form-urlencoded)

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

2. Base URL

{{restUrl}} = {{protocol}}://{{server}}:{{poort}}/mkg/web/v3/MKG

3. Retrieve a Record (GET)

Once logged in, you can make a data request using a GET request. We illustrate this with an example: reading the relationship table with a parameter, resulting in only 10 records.

GET {{restUrl}}/Documents/rela/?NumRows=10

The following values must be included in the header of this call:

• The cookie content with the JSESSIONID. This is provided after a successful login.

Cookie: JSESSIONID=[...] 

• The key of the API application from MKG.

X-CustomerID: {{apikey}} 

The result is HTTP status code 200 with a JSON starting with:

{
    "response": {
        "ResultData": [
            {
                "rela": [
                    {

4. Modify a Record (PUT)

With a PUT request, it is possible to modify existing data. We illustrate this with an example: changing the memo field of a relationship.

PUT {{restUrl}}/Documents/rela/1/

The following values must be included in the header of this call:

Cookie: JSESSIONID=[...] 
X-CustomerID: {{apikey}} 

The fields to be modified must be included in the body of this call as follows:

{
    "request":{
        "InputData":{
            "rela":[
                {
                    "rela_memo":"New memo text"
                }
            ]
    }
    }
}

The result is HTTP status code 200 with a JSON containing the key and the modified field with the updated value:

[...]

    "rela_num": 1,

    "rela_memo": "New memo text"

[...]

5. Add a Record (POST)

With a POST request, it is possible to add new data. We illustrate this with an example: creating a relationship.

POST {{restUrl}}/Documents/rela/

The following values must be included in the header of this call:

Cookie: JSESSIONID=[...] 
X-CustomerID: {{apikey}} 

The fields to be filled must be included in the body of this call as follows:

{
    "request": {
        "InputData": {
            "rela": [
                {
                    "rela_naam": "Relationship Name",
                    "rela_www": "www.domainname.eu"
                }
            ]
        }
    }
}

The result is HTTP status code 200 with a JSON containing the key and the modified field with the filled fields:

[...]

    "rela_num": *,

    "rela_naam": "Relationship Name",

    "rela_www": "www.domainname.eu"

[...]

6. Delete a Record (DEL)

With a DEL request, a record can be deleted. We illustrate this with an example: deleting a relationship.

DEL {{restUrl}}/Documents/rela/1

The following values must be included in the header of this call:

Cookie: JSESSIONID=[...] 
X-CustomerID: {{apikey}} 

The result is HTTP status code 200.

Examples of Calls

Various example calls

Base URL:
{{authUrl}} = {{protocol}}://{{server}}:{{poort}}/mkg/static/auth

{{restUrl}} = {{protocol}}://{{server}}:{{poort}}/mkg/web/v3/MKG

Login:
POST {{authUrl}}/j_spring_security_check?j_username={{gebruikersnaam}}&j_password={{wachtwoord}}

Logout:
POST {{authUrl}}/j_spring_security_logout

Logged-in User:
GET {{restUrl}}/User

Logged-in administration, fiscal year, and language:
GET {{restUrl}}/Settings?Settings=Administration,FiscalYear,Language

GET requests

For each of the calls below, the following values must be included in the header:

Cookie: JSESSIONID=[...]

X-CustomerID: {{apikey}}

Possible GET parameters:

Read endpoint.

GET {{restUrl}}/Documents/rela/

Read specific endpoint with known key value.

GET {{restUrl}}/Documents/rela/1/

Read endpoint with a limit on the number of results (parameter NumRows).

GET {{restUrl}}/Documents/rela/?NumRows=10

Read specific endpoint with specific field value (parameter Filter).

GET {{restUrl}}/Documents/rela?Filter=rela_naam = "MKG Nederland bv"

Read specific endpoint with multiple specific field values (parameter Filter).

GET {{restUrl}}/Documents/rela?Filter=rela_actief = true AND rela_plaats = "HENGELO"

Read endpoint with a limit on the number of fields in the result (parameter FieldList).

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

Read endpoint with sorting on a specific field (parameter Sort).

GET {{restUrl}}/Documents/rela?Sort=rela_naam

Read endpoint with various parameters.

GET {{restUrl}}/Documents/rela?Filter=rela_actief = true AND rela_plaats = "HENGELO"&NumRows=10&FieldList=rela_num,rela_naam,rela_plaats&Sort=rela_naam

Read underlying collection from a specific endpoint.

GET {{restUrl}}/Documents/rela/1/rela_adrs

Read underlying collection from a specific endpoint with known key value.

GET {{restUrl}}/Documents/rela/1/rela_adrs/1


Operators when using the Filter parameter:

Functions when using the Filter parameter on a date field:

* Optionally, a plus or minus number can be specified here. Examples: sys_dat_aanm = Today(3) --> today plus 3 days

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

PUT requests

For each of the calls below, the following values must be included in the header:

Cookie: JSESSIONID=[...] 
Content-Type: application/json
X-CustomerID: {{apikey}}

Modify multiple values of a record.

PUT {{restUrl}}/Documents/rela/1/

{
    "request":{
        "InputData":{
            "rela":[
                {
                    "rela_memo":"New memo text"
                }
            ]
        }
    }
}

Modify multiple values of a record in an underlying collection.

PUT {{restUrl}}/Documents/vorh/30220001/vorh_vorr/1

Body:

{
    "request":{
        "InputData":{
            "vorr":[
                {
                    "vorr_oms_1":"Modified description",
                    "vorr_order_aantal":99,
                    "vorr_bruto_prijs_ov":23.45,
                    "vorr_op_nacalculatie":false
                }
            ]
        }
    }
}

POST requests

For each of the calls below, the following values must be included in the header:

Cookie: JSESSIONID=[...] 
Content-Type: application/json
X-CustomerID: {{apikey}}

Create a record.

POST {{restUrl}}/Documents/rela/

Body:

{
    "request":{
        "InputData":{
            "rela":[
                {
                    "rela_naam":"New company name",
                    "rela_memo":"New memo text"
                }
            ]
        }
    }
}

Create a record.

POST {{restUrl}}/Documents/vorr/

Body:

{
    "request":{
        "InputData":{
            "vorr":[
                {
                    "vorh_num":"30220001",
                    "vorr_oms_1":"New description",
                    "vorr_order_aantal":99,
                    "vorr_bruto_prijs_ov":23.45,
                    "vorr_op_nacalculatie":false
                }
            ]
        }
    }
}

Create a record in an underlying collection.

POST {{restUrl}}/Documents/vorh/30220001/vorh_vorr/

Body:

{
    "request":{
        "InputData":{
            "vorr":[
                {
                    "vorr_oms_1":"New description",
                    "vorr_order_aantal":99,
                    "vorr_bruto_prijs_ov":23.45,
                    "vorr_op_nacalculatie":false
                }
            ]
        }
    }
}

DEL requests

For each of the calls below, the following values must be included in the header:

Cookie: JSESSIONID=[...] 
X-CustomerID: {{apikey}}

Delete record.

DEL {{restUrl}}/Documents/rela/1