¶ DELETE Operation
¶ Basic Information
DELETE operation allows you to delete selected record in an external system.
Let's have a simple example of a DELETE API Endpoint on URL https://test.api.com/v3/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. The example endpoint does not have request or response body – it just returns HTTP status code 200, if the delete operation was successful, and error HTTP status otherwise.
Tip: If your DELETE endpoint has a response body you can process it, too. See the optional step in the end of this guideline.
¶ 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(50002; "TestProvider_DeleteCustomer")
{
Caption = 'Delete 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 DELETE operation pointing to your API endpoint:
- The Command is
DELETE. - Enter
/Customerin the Endpoint field – i.e. the part of the URL without Provider URL (see Setting up API Provider). - The Description is up to you, but it has to be unique for the current provider.
- The Operation ID is the unique operation identifier. You will use this enum ID to call your operation from code.
- The Status is now
Open, meaning you can update the operation.
¶ Set up URL Parameters
To delete 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 are just id in this case:
- The Parameter is the name of the 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 the 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 option Encode URL.
Tip: If you have URL like https://test.api.com/v3/Customer/1, i.e. the
idis sent directly in URL string, you can use a similar approach. Just include the variable in the operation Endpoint field:
The code to set the variable is the same.
¶ How the Operation Works
Usually, you are deleting records that are already known to RESTwithUS. i.e. You created the Customer 01121212 record in an external system with a POST operation, and then maybe updated its data with a PUT/PATCH operation. If you did everything correctly, you should have an existing Connection that contains the record id in an external system:
The DELETE operation should then have two parts:
- RESTwithUS will first try to delete the record in an external system. Record is selected by External ID from the connection.
- If this operation ends with success, you need to delete the connection from RESTwithUS.
¶ Run the Operation
Let's run the operation for a first time and try to delete existing customer in an external system and delete related connection aftewards. You will need just 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
//For BC 18 and newer use record SystemId instead
//MappingId := APIScriptRWU.MAPPING(ProviderID::TestProvider,EntityID::TestProvider_Customer, Customer.SystemId);
IF MappingId = '' THEN //If there is no connection yet, throw error
Error('Customer does not exist in external system.');
APIScriptRWU.INIT(OperationID::TestProvider_DeleteCustomer); //Set the identifier for saving Batch Entries. This is mostly for debugging purposes.
APIScriptRWU.ENDPOINT(ProviderID::TestProvider,OperationID::TestProvider_DeleteCustomer); //Select the provider and his operation by description.
APIScriptRWU.ADD_VARIABLE('','CustomerId',MappingId); //Set the CustomerId variable in URL parameters
APIScriptRWU.EXECUTE(); //Start the operation.
ApiScriptRWU.DELETE_MAPPING(ProviderID::TestProvider,EntityID::TestProvider_Customer,Customer); //Delete the connection in RESTwithUS
//For BC 18 and newer use record SystemId instead
//ApiScriptRWU.DELETE_MAPPING(ProviderID::TestProvider,EntityID::TestProvider_Customer,Customer.SystemId);
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_DELETE_CUSTOMER');
APIScriptRWU.ENDPOINT('Test Provider','Delete 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:
- The value assigned to variable
CustomerId. - An error message, if the operation failed.
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:
You can click the number in marked columns to see the connection details:
As you can see, the connection for Customer 01121212 disappeared. And you should check, if the record was deleted in an external system, too.
Tip: For more details about connections see guideline Connections.
¶ (Optional) Processing Response Body
Let's say that the DELETE API operation returns a simple JSON body:
If so, then instead of deleting the connection with DELETE_MAPPING function you may want to process the response and leave everything on RESTwithUS.
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:
-
The
rootnode contains Customer record data, so let's connect it with the Customer table in Business Central. Set the Type toTableand the Object ID to the ID of Customer Table:18. -
Connections are stored at the Entity level, so you need to map the response to correct Entity:
a. Select theCustomerentity in the Entity ID field on therootnode.
b. Set theidnode to the Mapping TypeExternal IDand select the Entity ID too. (External IDmarks node which contains the record ID in an external system.) -
Match the
nonode with the correct field in Business Central. You will need that for finding the right connection.
Now select the root node and open Home / Details:
In the connection management fill in following fields:
- Set the Connection Operation to
Delete, because you want to delete the connection. - Fill in a Table View that defines, how to find the correct record in Business Central based on the JSON response data. You can use a helper function Generate Table View for that.
With these settings, RESTwithUS will delete the connection by itself and you don't need the line of code with DELETE_MAPPING anymore.