Skip to content
Support Portal
Request Demo
  • There are no suggestions because the search field is empty.

Defining API Variables

When you are initially setting up an API set, it is necessary to define a single endpoint URL that all of that API set’s functions will use when making API calls. However, every API function that is part of an API set exists for a different purpose, and it is unlikely that they will all use the same endpoint. The API Engine provides you with the ability to define variables that will augment or override an API set’s base URL on a function-by-function by function basis.

URL Parameters
URL parameters are settings that influence the nature of an API call. Parameters can be established to refine the type or volume of data that is requested of the external system, for example, if you wanted a particular API function to focus on a particular category or status of record type, you would append the necessary parameter to its endpoint.


To define URL parameters:

  1. With the relevant API function selected on the API Functions page, choose the API Variables ribbon, then choose the URL Parameters action.
  2. Choose a new line and enter a check mark in the Auto Build Request field. This will instruct the API Engine to automatically include the variable as part of API requests to the external system.
  3. By default, a value will be assigned in the Auto Build Sequence field, but you can change it, if desired. If you have multiple API variable lines, you can use this field to instruct the API Engine how to sequence them as part of API requests to the external system.
  4. In the Name field, enter a name to identify the API parameter
  5. In the Variable Value Type field, choose the type of parameter you want to create. The selection you make in this field depends on the type of parameter you want to define:
    1. If you want to define a tag, choose the Text Value option.
    2. If you want to define a key value, choose the Key Value Text option.
  6. In the Value Processing Type field, choose the type of parameter you want to create:
    1. Static: The parameter will be entered as a static value.
    2. Parameter Record: a variable parameter that is defined at runtime.
  7. The selected variable processing type will determine the remainder of your setup activities:
    1. If the value processing type is Static:
      1. Enter the parameter value in the Static Value field. This will be included as part of the endpoint URL, so this syntax must adhere to the external system’s API guidelines.
      2. In you are defining a key tag, you must also enter the key in the Static Name field. This will be included as part of the endpoint URL, so this syntax must adhere to the external system’s API guidelines.
    2. If the value processing type is Parameter Record:
      1. Enter or use the AssistButton in the Value Table No. field to assign a table to be used in defining the variable path. This could be a standard Business Central table, or a custom one that has been created for a specific organization.
      2. Enter or use the AssistButton in the Value Field No. field to assign a field from the specified value table to be used in defining the variable path. This could be a standard Business Central table, or a custom one that has been created for a specific organization.
  8. In the Variable Value Null Behavior field, use the dropdown to instruct the API Engine how to handle variable requests that are cannot be resolved during the API call.

URL Paths
Because separate API functions exist for different API calls, it is necessary to define unique endpoint URLs for each one.  It is possible to define static path values for an API function in the API Function table, but for variable path values, it is necessary to use API variables. You can also use API variables for static path values, if desired.


To define URL paths:

  1. With the relevant API function selected on the API Functions page, choose the API Variables ribbon, then choose the URL Paths action.
  2. Choose a new line and enter a check mark in the Auto Build Request field. This will instruct the API Engine to automatically include the variable as part of API requests to the external system.
  3. By default a value will be assigned in the Auto Build Sequence field, but you can change it, if desired. If you have multiple API variable lines, you can use this field to instruct the API Engine how to sequence them as part of API requests to the external system.
  4. In the Name field, enter a name to identify the API variable.
  5. In the Variable Value Type field, choose the Text Value option. URL paths are always entered as text.
  6. In the Value Processing Type field, choose the type of path value you want to create:
    1. Static: The path will be entered as a static value
    2. Parameter Record: a variable path that is defined at runtime according to one or more parameters.
  7. The selected variable processing type will determine the remainder of your setup activities:
    1. If the value processing type is Static, enter the path value in the Static Value field. This will be included as part of the endpoint URL, so this syntax must adhere to the external system’s API guidelines.
    2. If the value processing type is Parameter Record:
      1. Enter or use the AssistButton in the Value Table No. field to assign a table to be used in defining the variable path. This could be a standard Business Central table, or a custom one that has been 
        created for a specific organization.
      2. Enter or use the AssistButton in the Value Field No. field to assign a field from the specified value table to be used in defining the variable path. This could be a standard Business Central table, or a custom one that has been created for a specific organization.
  8. In the Variable Value Null Behavior field, use the dropdown to instruct the API Engine how to handle variable requests that are cannot be resolved during the API call.


URL Overrides

It is possible to completely override an API set’s endpoint for a given API function. When an API function is executed, any URL overrides that have been defined for that function will be used for the related API call. While not as dynamic as the other API variable options, this can be a quick and easy way to configure an API function’s endpoint if a high level of variability to not necessary.

To define URL overrides:

  1. With the relevant API function selected on the API Functions page, choose the API Variables ribbon, then choose the URL Overrides action.
  2. Choose a new line and enter a check mark in the Auto Build Request field. This will instruct the API Engine to automatically include the variable as part of API requests to the external system.
  3. By default,ult a value will be assigned in the Auto Build Sequence field, but you can change it, if desired. If you have multiple API variable lines, you can use this field to instruct the API Engine how to sequence them as part of API requests to the external system.
  4. In the Name field, enter a name to identify the API variable.
  5. In the Variable Value Type field, choose the Text Value option. Override URLs are always entered as text.
  6. In the Value Processing Type field, choose the Static option.
  7. In the Static Value field, enter the URL you want the related API function to use when making API calls to the external system.


The URL override setup is complete. The next time the API function is executed, the API call will be made to this override value, rather than the related API set’s default endpoint.

Next: Defining API Mappings