API Messages

All content related to an API call is entered as a separate “API message” in Business Central. Each API message contains an API call’s response and request data, as well as other information. This can assist in testing and troubleshooting activities, as it presents all information related to a given API call in a single place.

There are five stages to an API message’s “lifecycle:”

1. Message Initialization: the API function that will manage the API call is chosen, and any related API parameters are added.
2. Build Request: the request is built, based on the configuration of the related API function.
3. Send Request: the request is sent from Business Central to the external system/platform.
4. Receive Response: a response to the API call is retrieved into Business Central from the external system/platform.
5. Process Response: the API message’s data buffer is built from the response data, and data is processed in Business Central according to any related mappings.

To view API messages:

• Choose the looking glass in Business Central.  Enter API Messages and then choose the related link.
• Open the API message you want to review. Depending on the frequency of API function execution, there may be a large volume of API messages. Use filters and sorting to locate the necessary record.

You can also view all of the API messages that have generated for a specific API function from the API Functions page by selecting an API function line, choosing the Home ribbon and then choosing the API Messages action.

On the API Message page, different types of data related to the API message are presented on separate FastTabs:

• General: basic information about the API message, including the API set and API function for which it was created and various status values.
• Processing Timestamps: start and finish times for the execution of the related request, data buffer, and response processes.
• Related API Messages:
• Parameters: any parameters have been defined as part of the related API call.
• Request: the data contained within the request that was sent from Business Central to the external system.
• Response: the data contained within the response that was retrieved into Business Central from the external system. The response data is presented in a “raw” character stream on this FastTab; you can view the message’s data buffer to see a more structured presentation of the message response.
• Query Request: the content of the query that was sent from Business Central to the external system.

In practice, an API is completely processed when it is created due to the execution of an API function. However, for testing purposes, it is possible to manually set up an API message. You can then execute this message directly from the API Message page by choosing the Actions ribbon, then choosing one of the following options:

• Execute: this will instruct the API Engine to execute the API message in its entirety. The API message will be fully processed.
• Manual Processing: this submenu presents different stages of the API message’s lifecycle. In this way, you can manually step through each stage to review the result.

Adding API Parameters to an API Message
An API message will oftentimes have one or more parameters influence the nature of the API call. Each parameters presented in a separate line on the Parameters FastTab.

In general, parameters are determined through the configuration that has taken place for the related API function and automatically entered on the Parameters FastTab. However, when developing or testing functionality, it may be useful to make parameter adjustments directly to an API message. After making these adjustments, you can execute the API message and review the results.

To add an API parameter to an API message:

• On the Parameters FastTab, choose the Add New Parameter action.
• Choose one of the available parameter options:
  • Table Record: the API Engine will present a list of tables in Business Central. Locate the desired table, then choose the value in the ID field to view a list of records in that table. From here, you can choose the record that you want to send as part of the API call’s request. Note that many API calls a case-sensitive; it is recommended that you choose a record’s description, rather than code, when adding a table parameter.
  • Key Value: enter the parameter key (the type of information you want to send as part of the API call’s request) and its value (the specific value of that information type you want to send) in the respective Keyand Value fields.
    

Message Data Buffers
The content of an API call’s response from the external system is presented in two formats:

• A “raw” character stream is presented in the Response FastTab on the API Message page.
• A more structured version of the response data is entered as a “message data buffer.” This presents the data according to parent-child relationships, field designation, and so forth. Message data buffers can be processed via JSON or XML; this setting is defined when you are setting up the related API function.