¶ GET Multiple Records Operation
¶ Basic Information
GET operations allow you to retrieve data from an external system. Sometimes you want to get one specific record (see guideline GET Single Record) and sometimes the API returns a list of records, which you can process.
Let's have a simple example of the GET API Endpoint on URL https://test.api.com/v3/Customers which returns a list of Customers:
The result JSON node contains an array of Customers. Each customer has its own id in an external system (so called External ID). For the sake of simplicity let's say that the API returns Business Central Customer No. in no node. And there are more fields like customer name, address, city, etc.
¶ Create New Operation
To call this API endpoint you need to create a new Operation.
If you are creating your own AL extension that should implement connection with some API provider, the recommended way to start is to add your operation to Operation ID RWU enum:
enumextension 50002 "Test Operation ID RWU" extends "Operation ID RWU"
{
value(50005; "TestProvider_GetAllCustomers")
{
Caption = 'Get All Customers (Test Provider)';
}
}
Tip: You can skip this step for testing purposes and call your operations with provider description instead of enum ID. However, this is not recommended for production applications.
Now select your API provider from the list and open Operations:
Create a new GET operation pointing to your API endpoint:
- Command is
GET. - Enter
/Customersin the Endpoint field – i.e. the part of the URL without Provider URL (see Setting up API Provider). - Description is up to you, but it has to be unique for the current provider.
- Operation ID is the unique operation identifier. You will use this enum ID to call your operation from code.
- Status is now
Open, meaning that you can update the operation.
With GET operations you do not send any JSON data in a request, but you are getting data in the JSON response body.
¶ Response Body
To create a response body and map the JSON data to Business Central tables and fields select your operation from the list and open Response Body:
Initially, the response body is empty, so use function Payload / Import Payload, paste an example of JSON response and press OK:
RESTwithUS will generate response structure for you and you just need to map it to Business Central tables and fields:
Recommended way how to proceed is to use Entities and define the JSON schema in one place (see guideline Working with Entities). But let's now just create simple GET request and map it to Business Central fields.
-
The
resultnode contains Customer records, so let's connect it with Customer table in Business Central. Set Type toTableand Object ID to the ID of Customer Table:18. -
If you want to store connections between records in Business Central and an external system, it must be done on Entity level. First go to provider Entities and create a new entity called
Customer(if you haven't done that already for another operation):
Now map the JSON response to the entity:
a. Select theCustomerentity in the Entity ID field on theresultnode.
b. Setidnode to Mapping TypeExternal IDand select the Entity ID, too. (External IDmarks node which contains the record unique ID in an external system.)
c. Setnamenode to Mapping TypeDescriptionand select the Entity ID, too. (This is just for easier visual searching in connections.) -
Set up fields which are both in Business Central record and a record in an external system.
-
Let's say that the node
phonesis optional – if a Customer in an external system does not have any phone number, the node will be missing in JSON body. With default settings this may throw an error, but you can mark the node as optional by setting MinOccurs toZero.
Tip: If you do not want to map the result to Business Central fields or you are planning to process the API response directly in code, you can skip steps 1-4 and have a look at guideline Processing API Response with Code.
¶ Set up Connection Between Business Central and an External System
Now you need to specify, how should RESTwithUS search for matching records in Business Central. In the example you have JSON field no containing Customer No. from Business Central, so it should be easy.
All connection mappings are done on the nodes with Type Table. Select the result node then and open Home / Details:
First you need to select the Connection Operation. Let's select Create or Update option here. You are getting Customer list from an external system and then creating new connection for a Customer, that has no connection yet – or maybe updating the connection description, if it has changed.
Now you need to fill in Table View field which defines, how to search for the matching record in Business Central. You can write it manually, or you can use helper function Generate Table View:
In this scenario you are matching the records by Customer No. so select the No. key and press OK. RESTwithUS will generate a Table View based on the selected table key:
As you can see, this is a simple table view expression meaning:
- Sort the Customer table by No. field for faster search.
- Then look for a record, where the No. field has a value
{{Field1}}(field number 1 from the current table) – and previously you defined thatField 1of a Customer table is in the JSON nodeno.
Please note, that these settings will just set up a Connection, i.e. RESTwithUS will now know which record in Business Central relates to which record in an external system. If you want to write data to Business Central tables, you will need to use the Table Operation settings and a RapidStart package (see guideline Updating Data in Business Central).
¶ Run the Operation
Let's run the operation for a first time. You will need just three lines of code for that using the API Script RWU codeunit. Just don't forget to Release both the entity and the operation before running the code.
var
APIScriptRWU: Codeunit "API Script RWU";
ProviderID: Enum "Provider ID RWU";
OperationID: Enum "Operation ID RWU";
APIScriptRWU.INIT(OperationID::TestProvider_GetAllCustomers); //Set the identifier for saving Batch Entries
APIScriptRWU.ENDPOINT(ProviderID::TestProvider,OperationID::TestProvider_GetAllCustomers); //Select the provider and his operation
APIScriptRWU.EXECUTE(); //Start the operation
Tip: For more API Script functions see guideline API Script Functions Reference.
For testing purposes you can call the provider and operation by their description. However, this is not recommended for production applications:
APIScriptRWU.INIT('TEST_PROVIDER_GET_ALL_CUSTOMERS');
APIScriptRWU.ENDPOINT('Test Provider','Get All Customers');
APIScriptRWU.EXECUTE();
¶ Check the Results
¶ Batch Entries
Now you can check the results. First go to Operations, select the operation from the list and open Related / Batch Entries from the menu:
Here you can see all the details about the operation run like:
- Response JSON preview in the
rootnode value. - The matching Business Central record in Record ID column.
- All data, that were sent during request or received during response.
Tip: You set the Batch Code value with
INITfunction and you can use whatever string you want. Just remember that each new call of an operation deletes all previous Batch Entries with the same Batch Code. For more details see guideline Batch Entries.
¶ Connections
Connections are maintained on an Entity level. To check them select your API Provider and choose Entities from the menu:
- Healthy Connections are records, that were successfully matched between both systems (e.g. Customers existing in both systems).
- Broken Connections are records returned by the API service – but RESTwithUS was not able to match the data with any record in Business Central (e.g. the Customer is missing in Business Central or has a wrong number in an external system).
You can click the number in marked columns to see the connection details:
As you can see, the GET operation returned three records and all were successfully matched with a record in Business Central. Plus the record id in an external system was saved in External Id column for further use in any other operation.
Tip: For more details about connections see guideline Connections.
¶ What's Next?
You have finished a simple GET operation and got some basic data from an external API with the help of RESTwithUS. So what's next? Well, you can for example:
- Save the data from an external system to Business Central (see Updating Data in Business Central).
- Process the data with code (see Processing API Response with Code).
- Ask the external API for a filtered subset of the data (see Filtering result).
- If the API returns paged results, you may need to set up paging (see Paging result).