Using Read Endpoints
Consuming a Read Endpoint Using Postman
Postman is an API Platform/Tool, allowing you to call API endpoints. When used with Data Braider, it is used to send and receive data through the API Endpoints you have created.
This guide will assume you understand how Postman works and know how to set up the baseline structure to be able to communicate with Data Braider. (A basic setup would include setting up the correct Environment, supplying it the Company ID, and the API URL to your Business Central Server that has Data Braider installed.)
The company ID can be received through an API call to the default engine, here is an example of such a call to a Business Central Cloud server (this URL includes the tenant ID, e6530ea3-74f0-4147-9b06-0554afd9ae53):
This example API call will give you information regarding your company, including the Company ID you require to set up your Postman Environment to start using it with Data Braider.
The response you will get back with look like the following:
{
“@odata.context”: “[https://api.businesscentral.dynamics.com/v2.0/e6530ea3-74f0-4147-9b06-0554afd9ae53/APIBook/api/v2.0/$metadata#companies](https://api.businesscentral.dynamics.com/v2.0/e6530ea3-74f0-4147-9b06-0554afd9ae53/APIBook/api/v2.0/$metadata#companies)”,
“value”: [
{
“id”: “86e811fb-de3a-ed11-bbae-6045bd8e554a”,
“systemVersion”: “21.0.46256.46853”,
“timestamp”: 4283,
“name”: “CRONUS USA, Inc.”,
“displayName”: “”,
“businessProfileId”: “”,
“systemCreatedAt”: “2022-09-23T01:28:11.793Z”,
“systemCreatedBy”: “00000000-0000-0000-0000-000000000001”,
“systemModifiedAt”: “2022-09-23T01:28:11.793Z”,
“systemModifiedBy”: “00000000-0000-0000-0000-000000000001”
}
As you can see above, your response data will give you the Company ID you require, along with the name of the company, so you are able to identify the correct company, in case you have multiple companies set up in your Business Central Environment.
Once you have fetched the Company ID you require, your API calls to Data Braider will look like the following example: https://api.businesscentral.dynamics.com/v2.0/e6530ea3-74f0-4147-9b06-0554afd9ae53/APIBook/api/v2.0/companies(86e811fb-de3a-ed11-bbae-6045bd8e554a)/read
As you can see, the Company ID has been supplied within the URL used to call an endpoint, make note of the ‘/read’ at the end, this reflects the use of a READ endpoint in Data Braider, used to receive information from your Business Central Environment.
The READ endpoint is quite straightforward, as it will fetch whatever data you have supplied in your Data Braider API Endpoint.
The READ type endpoint can be called with both Get and Post.
Basic GET Calls to the Read Endpoint
Performing a Get call require you to extend your URL a little bit further to make it know which endpoint it is calling, the example below shows you how you extend the URL to reach a specific endpoint, Customers in this instance: https://api.businesscentral.dynamics.com/v2.0/e6530ea3-74f0-4147-9b06-0554afd9ae53/APIBook/api/v2.0/companies(86e811fb-de3a-ed11-bbae-6045bd8e554a)/read(‘CUSTOMERS’)
When performing this Get call to your Read Endpoint in Data Braider, you would receive a response like following:
{
"@odata.context": "[https://api.businesscentral.dynamics.com/v2.0/e6530ea3-74f0-4147-9b06-0554afd9ae53/APIBook/api/v2.0/$metadata#companies(86e811fb-de3a-ed11-bbae-6045bd8e554a)/read/$entity](https://api.businesscentral.dynamics.com/v2.0/e6530ea3-74f0-4147-9b06-0554afd9ae53/APIBook/api/v2.0/$metadata#companies(86e811fb-de3a-ed11-bbae-6045bd8e554a)/read/$entity)",
"@odata.etag": "W/\"JzIwOzEyMjA2NTUxMDg1Mzg0NDQ1MDA1MTswMDsn\"",
"code": "CUSTOMERS",
"description": "",
"endpointType": "Read Only",
"outputJSONType": "Hierarchy",
"jsonResult": "[{\"_delta\":\"\",\"level\":10000,\"sourceTableNumber\":18,\"sourceTableName\":\"Customer\",\"pkString\":\"No.=CONST(10000)\",\"sourceSystemId\":\"86E811FB-DE3A-ED11-BBAE-6045BD8E554A\",\"data\":{\"No\":\"10000\",\"Name\":\"Sailing Essentials\",\"timestamp\":1699021023}},{\"_delta\":\"\",\"level\":10000,\"sourceTableNumber\":18,\"sourceTableName\":\"Customer\",\"pkString\":\"No.=CONST(20000)\",\"sourceSystemId\":\"7685C3EF-C740-EE11-BE71-6045BDC89DF0\",\"data\":{\"No\":\"20000\",\"Name\":\"Camping Tools\",\"timestamp\":1699020983}},{\"_delta\":\"\",\"level\":10000,\"sourceTableNumber\":18,\"sourceTableName\":\"Customer\",\"pkString\":\"No.=CONST(30000)\",\"sourceSystemId\":\"7A85C3EF-C740-EE11-BE71-6045BDC89DF0\",\"data\":{\"No\":\"30000\",\"Name\":\"School of Fine Art\",\"timestamp\":1692697413}},{\"_delta\":\"\",\"level\":10000,\"sourceTableNumber\":18,\"sourceTableName\":\"Customer\",\"pkString\":\"No.=CONST(40000)\",\"sourceSystemId\":\"7E85C3EF-C740-EE11-BE71-6045BDC89DF0\",\"data\":{\"No\":\"40000\",\"Name\":\"Alpine Ski House\",\"timestamp\":1692697413}},{\"_delta\":\"\",\"level\":10000,\"sourceTableNumber\":18,\"sourceTableName\":\"Customer\",\"pkString\":\"No.=CONST(50000)\",\"sourceSystemId\":\"8285C3EF-C740-EE11-BE71-6045BDC89DF0\",\"data\":{\"No\":\"50000\",\"Name\":\"Relecloud\",\"timestamp\":1692697413}}]",
"filterJson": "",
"pageStart": 0,
"pageSize": 0
}
Looking at the response like this, it is quite difficult to make out what is what, but there are tools that can make this more readable (see Utilities). The key understanding is that the jsonResult contains a stringified JSON result. Use your preferred manner of converting this string back to a JSON.
Here is an example of the first item in the above response, after making it more readable:
{
"_delta": "",
"level": 10000,
"sourceTableNumber": 18,
"sourceTableName": "Customer",
"pkString": "No.=CONST(10000)",
"sourceSystemId": "86E811FB-DE3A-ED11-BBAE-6045BD8E554A",
"data": {
"No": "10000",
"Name": "Sailing Essentials",
"timestamp": 1699021023
}
In this example, we have set up an Endpoint in Data Braider to give the “No.” and “Name” of all customers in our Business Central environment. This will include the timestamp (last datetime it was changed) automatically.
Reading Data with Filtering via POST calls
To extend on this functionality a little bit more, we can use Postman POST function instead of GET, this will allow us to supply a filter on our Read Endpoints in Data Braider.
To set up a filter, you will need to collect some additional information, The Table Name (or Number) as well as what field Name (or Number) we wish to filter on, out of the fields that we have made available in the Data Braider Endpoint we have created.
In our example, we only have Customer “No.” and “Name” available; therefore we will put a filter on the “Customer” Tables “No.” field.
In Postman, we will go over to the “Body” section and supply the necessary JSON entry required to perform a Read with Filters.
A Filter body entry requires some specific information to function properly:
- A Code entry line to reflect the Endpoint Call Code
- a FilterJson with our Json Filter code
For our example we are targeting our Endpoint called “CUSTOMERS”, the Table connected on the endpoint, “Customer”, the Field on the Table we wish to filter on, “No.” (make note, this field has a (.) at the end and is required for filter on this field to work), and the Filter we wish to supply, “20000” in our example:
{
"code": "CUSTOMERS",
"filterJson":"[{\"table\":\"Customer\", \"field\":\"No.\", \"filter\":\"20000\"}]"
}
The FilterJson entry can also be adjusted to filter on the number for the Customer Table (18), as well as the Field Number for “No.” (1), and still give the same result, as in this example:
{
"code": "CUSTOMERS",
"filterJson": "[{\"table\":\"18\",\"field\":\"1\",\"filter\":\"20000\"}]"
}
These can be found in our Data Brader API Endpoint within our Business Central instance, Open up the Endpoint in question, and locate the Endpoint Line section:
- The Table Number, this can be used to substitute “Customer”, in the FilterJson code line.
- A clickable FlowField, click on this to open a list with all Fields included in our selected Endpoint, to locate the Field Number(s).
- The Field Number, this can be used to substitute “No.”
A filter is supplied in the Body of the Postman API Call, and in addition, when using a filter, we have also lifted out the Endpoint Call Code (‘CUSTOMERS’) in this example) from the URL, and insert it into the body of code as “CUSTOMERS”.
As you can see in the example below, we have lifted out the (‘Customer’) from our URL, and instead put it in our code line in the body, as well as supplied a FilterJson line with the filter parameters we require:
Make note, in this example, we are making use of Variables to supply the correct URL, this is shown in the example below as {{baseurl}} and {{companyid}}, as this is frequently used for developers when working in multiple Business Central instances. This can be substituted with the complete URL instead.
When we click “Send” we will receive a filtered Read view of our Customers, showing us only entries that contain the given filter (20000):
{
"@odata.context": "[http://docker-bc22-w1-default:7048/BC/api/sparebrained/databraider/v2.0/$metadata#companies(86e811fb-de3a-ed11-bbae-6045bd8e554a read/$entity](http://docker-bc22-w1-default:7048/BC/api/sparebrained/databraider/v2.0/$metadata#companies(86e811fb-de3a-ed11-bbae-6045bd8e554a read/$entity)",
"@odata.etag": "W/\"JzE5Ozg2ODIwODIyMDg0ODgwOTgxMTcxOzAwOyc=\"",
"code": "CUSTOMERS",
"description": "",
"endpointType": "Read Only",
"outputJSONType": "Hierarchy",
"jsonResult": "[{\"_delta\":\"\",\"level\":10000,\"sourceTableNumber\":18,\"sourceTableName\":\"Customer\",\"pkString\":\"No.=CONST(20000)\",\"sourceSystemId\":\"86E811FB-DE3A-ED11-BBAE-6045BD8E554A\",\"data\":{\"No\":\"20000\",\"Name\":\"Camping Tools\",\"timestamp\":1699020983}}]",
"filterJson": "[{\"table\":\"Customer\",\"field\":\"No.\",\"filter\":\"20000\"}]",
"pageStart": 0,
"pageSize": 0
}
The filtering used within the endpoint reflects a filter that you would supply within your Business Central instance, i.e you can write the Filter Text containing (<, >, =, *, |, &, ?, etc.), as you would inside Business Central. Here are some examples on valid filter entries: Anything Starting with 20:
{
"code": "CUSTOMERS",
"filterJson":"[{\"table\":\"Customer\",\"field\":\"No.\",\"filter\":\"20*\"}]"
}
20000 OR 30000:
{
"code": "CUSTOMERS",
"filterJson":"[{\"table\":\"Customer\",\"field\":\"No.\",\"filter\":\"20000|30000\"}]"
}
Anything Bigger than 20000:
{
"code": "CUSTOMERS",
"filterJson":"[{\"table\":\"Customer\",\"field\":\"No.\",\"filter\":\">20000\"}]"
}
Anything Not Equal to 20000:
{
"code": "CUSTOMERS",
"filterJson":"[{\"table\":\"Customer\",\"field\":\"No.\",\"filter\":\"<>20000\"}]"
}
Anything Smaller or Equal to 20000:
{
"code": "CUSTOMERS",
"filterJson":"[{\"table\":\"Customer\",\"field\":\"No.\",\"filter\":\"<=20000\"}]"
}
In addition to this, you are also able to insert multiple filters at once, as in this example, we are supplying a filter on both the No. field, as well as the Name field:
{
"code": "CUSTOMERS",
"filterJson": "[{\"table\":\"Customer\",\"field\":\"No.\",\"filter\":\">20000\"},{\"table\":\"Customer\",\"field\":\"Name\",\"filter\":\"School*\"}]"
}
Pay attention to how the filters are split up, both entries are contained within a ({) and (}), and divided by a (,).
If you would happen to write an incorrect FilterJson string, you would get the following useful error as a response:
{
"@odata.context": "[http://docker-bc22-w1-default:7048/BC/api/sparebrained/databraider/v2.0/$metadata#companies(b14698e2-c740-ee11-be71-6045bdc89df0)/read/$entity](http://docker-bc22-w1-default:7048/BC/api/sparebrained/databraider/v2.0/$metadata#companies(b14698e2-c740-ee11-be71-6045bdc89df0)/read/$entity)",
"@odata.etag": "W/\"JzE5OzM0Mjc2MTQ5NzQwNjM5OTAyNDAxOzAwOyc=\"",
"code": "CUSTOMERS",
"description": "",
"endpointType": "Read Only",
"outputJSONType": "Hierarchy",
"jsonResult": "[{\"Row\":0,\"Column\":1,\"Error\":true,\"Detail\":\"There were issues with the filters provided:\"},{\"Row\":1,\"Column\":2,\"Error\":true,\"Detail\":\"Field No not found\"}]",
"filterJson": "[{\"table\":\"Customer\",\"field\":\"No\",\"filter\":\">20000\"},{\"table\":\"Customer\",\"field\":\"Name\",\"filter\":\"School*\"}]",
"pageStart": 0,
"pageSize": 0
}
Make note that the only thing that was wrong with the sent FilterJson string was the Field name, written as “No” instead of “No.”, missing the required (.).