¶ Debugging, Log and Error Handling
When you are running API operations in a test or production environment, you will sooner or later run into the following situations:
- The API operation is not behaving as expected. So what happened?
- In some circumstances the API operation returns error HTTP status. How to handle it?
If you are looking for an answer to the first question, you will find it in the Debugging and Log section – and the answer to the second question can be found under Error Handling.
¶ Debugging
RESTwithUS offers two main sources of information, that can help you determine, what is happening during the request: Batch Entries and request/response Log.
¶ Batch Entries
Every operation run is using Batch Entries in the background. They are the main tool for creating requests and processing responses and there is a lot of information about the whole operation run. To access operation batch entries select your operation from the list and open Related / Batch Entries:
This is an example of batch entries for a simple PUT operation (update Customer data). So what can you for example find there?
- Request and response details and JSON preview
- Values and variables added with code in yellow color
- Related records in Business Central and related RESTwithUS entities
For more information about batch entries (how to save them, set the level of stored information etc.) see guideline Batch Entries.
¶ Log
If you want to log every request and response, you can set it up in the Log tab of provider details (select a provider from the list and open Details). Each operation call results will be then saved based on the settings:
- Standard Log Type – these settings apply to all operation runs, that do not cause transaction rollback (i.e. all successful requests; but also all responses with error HTTP status, that can be processed without causing an error – when the Response Error is set to
Custom MessageorProcess as Success). - Failure Log Type – applies to all operation runs, that cause a transaction rollback.
Saved logs can be accessed by selecting Related / Log action in provider or operation list (1). If you select different options for Standard and Failure Log Type or have changed the settings in the past, RESTwithUS will show a notification that provides access to all applicable log locations (2).
You can disable log on the operation level in Operation Details using Disable Log option. Use this for operations sending or receiving sensitive information like passwords, tokens etc.
RESTwithUS currently supports following options to save request/response log:
¶ Database
Database log option saves all important information into Business Central database and the logs can be viewed and filtered on a standard page.
Tip: Set up a retention policy to automatically delete old logs. You can use the link in provider details for basic setup – and manually update the policy if you need to use it for more than one provider.
¶ File
If the file log is turned on, RESTwithUS will save the request and response information into simple text files in the folder with each operation run. Each operation has its own unique GUID:
Example of a request log with URL, headers and JSON body:
Example of a response log with response JSON body:
Log files are not available in cloud environment (Business Central Online).
¶ Azure Blob Storage
Azure Blob storage option is not implemented yet.
¶ Error Handling
All REST API operations are returning so-called HTTP status codes – see the full list for example here: https://en.wikipedia.org/wiki/List_of_HTTP_status_codes. But basically, anything starting with 200 is ok (200, 202, etc.) and anything starting with 400 or 500 is an error.
RESTwithUS is working with these status codes and if the API returns an error HTTP status code, RESTwithUS tries to handle the error based on some operation settings.
To set the operation error handling type select the operation from the list and open Details:
Default value of the Response Error field is Error. But let's take a look at all the different types of error processing:
¶ Error
This is the default RESTwithUS behavior. If an API operation returns error an HTTP status code, RESTwithUS will throw an error:
In the message, you can see the HTTP status code and the text or JSON body of the response.
If an operation ends with such an error, the following things happen:
- All processing is stopped. So if you are updating ten Customers in a batch and the second operation will end with an error, the rest of the Customers won't be processed.
- Unless you specifically called the
COMMITfunction, no data will be written into Business Central. No data meaning here really no data – not only updated fields in processed records but also RESTwithUS batch entries, connections, etc.
Tip: You can get the error text with
GETLASTERRORTEXTfunction.
¶ Custom Message
With Response Value field set to Custom Message an error HTTP status code will not throw an error, but the operation batch entries will look like following:
For the response there is only one line with the HTTP status code in Key column and the text or JSON body in Value column.
- The processing is not stopped. If you are updating ten Customers in a batch and the second operation will end with an error, the rest of the Customers will be processed – but the error operation will not finish nor write any data to Business Central.
- You need to handle the error in code – see the examples below.
var
APIScriptRWU: Codeunit "API Script RWU";
//Handle the response based on EXECUTE function result
if APIScriptRWU.EXECUTE() then
//Handle correct response
else
//Handle error response
//Get the last HTTP status code
StatusCode := APIScriptRWU.LAST_STATUS(); //Returns "400" for the example above
//Ge the last error text or JSON
ErrorMessage := APIScriptRWU.LAST_ERROR(); //Returns "{"error" : "Customer not found."}" for the example above
¶ Process as Success
With Response Value field set to Process as Success you need to do some additional settings. First you need to make an additional operation to process the error response:
In the operation Response Body import a sample of the error response. You can even update the body as usual, but let's keep it simple now:
Don't forget to Release the operation and then go back to the first one and open operation Details:
- Set Response Error to
Process as Success. - Select the error processing operation id in Error Schema Id field.
If the operation ends with an error status, the error response body will be processed with the schema of the Error Response operation. Batch entries will look like this:
The error JSON response was processed by the schema of Error Response operation and RESTwithUS generated batch entries based on the schema, so you can use standard API Script functions to process the response. If the error JSON is invalid or cannot be processed by the operation, RESTwithUS will generate an error batch entry similar to Custom Message option.
Plus you can now process the error response manually with code – see examples below or guideline Processing API Response with Code for more details.
var
APIScriptRWU: Codeunit "API Script RWU";
ResponseJSON: Text;
ErrorMessage: Text;
StatusCode: Text;
//Handle the response based on EXECUTE function result
if APIScriptRWU.EXECUTE() then
//Handle response, that was successfully processed by the standard or error schema
else
//Handle response, that cannot be processed - e.g. invalid JSON
//Get the last HTTP status code
StatusCode := APIScriptRWU.LAST_STATUS(); //Returns "400" for the example above
//Get the response JSON
ResponseJSON := APIScriptRWU.GET_RESPONSE_JSON();
//Get the value of response "error" node
ErrorMessage := APIScriptRWU.GET_RESPONSE_VALUE_BY_JPATH('$.error');