¶ GET Single Record Operation
¶ Basic Information
GET operations allow you to retrieve data from an external system. Sometimes you want to get more records at once (see guideline GET Multiple Records) and sometimes you want to ask an API just for one selected record.
Let's have a simple example of the GET API Endpoint on URL https://test.api.com/v3/Customer which returns data of a selected Customer. You need to provide the selected Customer id in URL parameter id, so the final URL may for example look like https://test.api.com/v3/Customer?id=1.
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(50006; "TestProvider_GetCustomer")
{
Caption = 'Get Customer (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 new GET operation pointing to your API endpoint:
- Command is
GET. - Enter
/Customerin 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 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.
¶ Set up URL Parameters
To get a specific Customer record you need to send its identifier in URL parameter id (the final URL may then look like https://test.api.com/v3/Customer?id=1). So select your operation from the list and open Related / URL Parameters:
Now fill in the request URL parameters which is just id in this case:
- Parameter is the name of URL parameter.
- You can fill in exact string into the Value of the parameter – but in this example you want to fill the
idparameter with code. So let's use a variable namedCustomerId(with a syntax{{VariableName}}) and let's make it required, so the final syntax is{{!CustomerId}}. - If you need to URL encode the parameter, you can check the option Encode URL.
- If the parameter is Optional, it will not appear in the url when the value is blank. You can use that to create a single operation with multiple filters (e.g. get the customer by id or get the list of all customers in one country with the same operation, based on the provided variables).
Tip: If you have URL like https://test.api.com/v3/Customer/1, i.e. the
idis sent directly in the URL string, you can use similar approach. Just include the variable in the operation Endpoint field:
The code to set the variable is the same.
¶ Response Body
To create response body and map 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 the function Payload / Import Payload, paste an example of JSON response and press OK:
RESTwithUS will generate a response structure for you and you just need to map it to Business Central tables and fields:
The recommended way on how to proceed is to use Entities and define the JSON schema in one place (see guideline Working with Entities). But now let's just define a simple GET response and map it to Business Central fields.
-
The
rootnode contains Customer record, 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 at the Entity level. Firstly, 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 therootnode.
b. Setidnode to Mapping TypeExternal IDand select the Entity ID, too. (External IDmarks node which contains the record 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 plan 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 record 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 root node and open Home / Details:
Firstly, you need to select the Connection Operation. Let's set Create or Update option here. You are getting a Customer record from an external system and then creating a 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 the Table View field which defines, how to find 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 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 the first time and try to get an existing customer's data. You will need only a few 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
Customer: Record "Customer";
APIScriptRWU: Codeunit "API Script RWU";
EntityID: Enum "Entity ID RWU";
ProviderID: Enum "Provider ID RWU";
OperationID: Enum "Operation ID RWU";
MappingId: Text;
Customer.GET('01121212'); //Get existing customer record
MappingId := APIScriptRWU.MAPPING(ProviderID::TestProvider, EntityID::TestProvider_Customer, Customer); //Get id of the customer in an external system from RESTwithUS connection
IF MappingId = '' THEN //If there is no connection yet, you need to set the id manually
MappingId := '1';
APIScriptRWU.INIT(OperationID::TestProvider_GetCustomer); //Set the identifier for saving Batch Entries
APIScriptRWU.ENDPOINT(ProviderID::TestProvider,OperationID::TestProvider_GetCustomer); //Select the provider and his operation
APIScriptRWU.ADD_VARIABLE('','CustomerId',MappingId); //Set the CustomerId variable in URL parameters
APIScriptRWU.EXECUTE(); //Start the operation.
To get the right record from an external system, you need to know its unique identifier (id in this case). If you have set up the Connection Management part correctly, RESTwithUS will save it to connections as an External Id with each API request.
Remember that the connections are managed on Entity level and each operation using the same entity is using the same connections. So if you for example already ran POST operation to create customer 01121212 or GET all customers operation, the id is saved in RESTwithUS connections and you can get it with MAPPING function.
However, if it's not saved yet, you need to set it up manually.
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_CUSTOMER');
APIScriptRWU.ENDPOINT('Test Provider','Get Customer');
¶ Check the Results
¶ Batch Entries
Now you can check the result. 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 value assigned to variable
CustomerId. - 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 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 customer 01121212 has a healthy connection and was successfully matched with a record in Business Central. Plus its 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 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).