Dynamic api

Introduction

Dynamic api gives an alternative way to handle the data. As opposed to the older model based handling. For benefits this functionality relies on the api’s business logic entirely and does not need adjustments to models once the api’s change.

It also allows to create as many request as you want against the same api and implements various data manipulation helper functions.

Defining requests

Requests are defined by either input parameters from the browser (query or post) or by static preset values. Preset values are values that are saved to the template during its save time and this means that changing values cannot be used with them.

The syntax of the requests is the following

Api name Name of the api in question, reference the dynamic data source docs in the editor for the full list of options.
Api Always has the value of Api, this tells the system that we intend to use the dynamic api functionalities.
HTTP Method The http method that is to be used for the api call.
- Get
- Post
- Put
- Patch
- Delete
- FTPGet
- FTPPut
Custom request name Custom name for the request you define, we use it later to set parameters and read the results.

Requests naming

Request names are case-sensitive. Prefer giving self-explanatory names to the requests, so they will not confuse while developing huge template with many requests. For example, if request made for v1/products and used method Get, then name it getProducts, but not something like request1, records, etc.

Also, GoErp have reserved names that cannot be used while defining the name for request.

Reserved names:

Session (with Capital S, session is ok to use)
Parameters (with Capital P)
Storage (with Capital S)

Using in a form

The definition of the name is given to the form input name and the endpoint to call from that api is given as the value.

Note that the value should not start with the character /.

<form method="get">
    <input name="ReportsApi.Api.Get.getProductsCall" value="v1/POSDay">
</form>

The call is made when the page is accessed only when the parameter is actually passed. In the sample above the parameter is registered in the form but is never actually sent as a parameter to the server. In order to load the data we would need to submit the form.

The method of the form would define how the parameter is passed to the server either via query parameter or a post parameter.

We can also load parameter into links to make the api to be called right away (before the page is enriched with data):

?ReportsApi.Api.Get.someReportsCall=v1/POSDay

This link would load the data when it is opened.

Defining static presets

When opening a page via url that has no query parameters then even if we have defined some api call into form they would not be triggered. Regular form values are not read from the template content, rather it is just written there to make the actual calls by the browser.

There is a way however to set defaults to parameters, these values are saved during template save time and are static values. This means that dynamic values that change in the template view process cannot be passed onto them, the values that are added to it are the exact values that will be used for the request.

This allows the request to be made with some default values and to make it load something when a page is opened without any parameters.

For this we can use the data-preset-val attribute on the inputs

<form method="get">
    <input name="ReportsApi.Api.Get.myReportsCall" 
           value="v1/POSDay" 
           data-preset-val="v1/POSDay">
</form>

Note that these do not need to be in the form as we might never send the parameter if we never intend to send the form. In this case a single hidden input that is not part of a form is enough.

<input type="hidden" name="ReportsApi.Api.Get.myStaticReportsCall"
       data-preset-val="v1/POSDay">

If the browser passes a parameter to the same value it will overwrite the preset value.

Url configuration static presets

From version 1.179.1 we can also set static preset values in the editor under the “URL configuration” menu. These name:value pairs work the same way as regular preset value definitions, but when defined here the values do not need to be in the template body at all.

Useful for pages that generate content that might not want to view the input but automatic loading of content is required.

Request parameters

Defining request parameters

To pass parameters to the api we will use similar syntax like the one we use to define the requests.

The custom request name here should match exactly the one we used to define the request.

In the following example we add the query parameter currencyId for the request we defined as myReportsCall

<form method="get">
    
    <input type="hidden" name="ReportsApi.Api.Get.myReportsCall" 
           value="v1/POSDay" 
           data-preset-val="v1/POSDay">

    <label for="currencyId">Currency ID</label>
    <input id="currencyId" type="number" 
           name="ReportsApi.Api.Query.myReportsCall.currencyId">

    <button type="submit">Fetch</button>
    
</form>

Default static values

Similar to the way we can give default values to requests we can also give default values to parameters.

Note that the values here are static meaning that we cannot add placeholders to the data-preset-val attribute. The value is being saved on template save time and will not change during the page view process.

<form method="get">
    
    <input type="hidden" name="ReportsApi.Api.Get.myReportsCall" 
           value="v1/POSDay" 
           data-preset-val="v1/POSDay">

    <!-- We make the page load with currency ID 1, however we still allow it to be overwritten by the parameter -->
    <label for="currencyId">Currency ID</label>
    <input id="currencyId" type="number" 
           name="ReportsApi.Api.Query.myReportsCall.currencyId" 
           data-preset-val="1">
    
    <button type="submit">Fetch</button>
    
</form>

If the browser passes a parameter to the same value it will overwrite the preset value.

Parameter types

Parameters are passed either via query or as post parameters. Samples here are generated into form inputs, but they can as well be used in url query parameters (name=value).

Query

We define the query type with the type name Query

<input type="number" 
       name="ReportsApi.Api.Query.myReportsCall.currencyId">

If we do not want to lose the value from the form field we can set the value to read from the request.

<input type="number" 
       name="ReportsApi.Api.Query.myReportsCall.currencyId" 
       value="{{ .Data.ReportsApi.Api.Requests.myReportsCall.Queries.currencyId }}">

This means the input will keep its value after the possible form submit and page reload

QueryBulk

Allows to pass as many query parameters as needed using one input. Parameter name here doesn’t matter actually as it would be ignored anyway, but we can always name it url just to make it clear to read

<input type="hidden" 
       name="CaFaApi.Api.QueryBulk.getConf.url"
       value="application=my-app&level=Company&name=dynamic-sample">

And to access those parameters just use the same Queries field like with regular Query parameters

<h1>Query parameters from bulk</h1>
<p>App: {{ .Data.CaFaApi.Api.Requests.getConf.Queries.application }}</p>
<p>Level: {{ .Data.CaFaApi.Api.Requests.getConf.Queries.level }}</p>
<p>Name: {{ .Data.CaFaApi.Api.Requests.getConf.Queries.name }}</p>

PostParam

Mostly for api’s that use urlencoded parameters or multipart/form-data (example: ErplyApi). Supports file uploading as well.

PostParam also used with FTP related calls to pass additional parameters like username, password and path.

We define the query type with the type name PostParam

<input type="number" 
       name="ErplyApi.Api.PostParam.getProducts.productID">

If we do not want to lose the value from the form field we can set the value to read from the request.

<input type="number" 
       name="ErplyApi.Api.PostParam.getProducts.productID"
       value="{{ .Data.ErplyApi.Api.Requests.getProducts.PostParams.productID }}">

And to uploading the file:

<input type="hidden" name="CDNApi.Api.Post.r1" value="images">
<input type="file" name="CDNApi.Api.PostParam.uploadImage.image">

We define the query type with the type name Header

<input id="currencyId" type="number" 
       name="ErplyApi.Api.Header.getProducts.myHeader">

If we do not want to lose the value from the form field we can set the value to read from the request.

<input type="number"
       name="ErplyApi.Api.Header.getProducts.myHeader"
       value="{{ .Data.ErplyApi.Api.Requests.getProducts.Headers.myHeader }}">

Path

If the api expects one of the parameters to be a path parameter we would define the request with a placeholder and follow it up with a value for this placeholder.

<input type="hidden" name="PricingApi.Api.Get.myCall"
       value="v1/price-lists/summary/{id}">

<input type="number" name="PricingApi.Api.Path.myCall.id" value="1">

Note here that the placeholder in the request definition needs to match that of the parameter name.

If we do not want to lose the value from the form field we can set the value to read from the request.

<input type="number"
       name="PricingApi.Api.Path.myCall.id"
       value="{{ .Data.PricingApi.Api.Requests.myCall.PathParams.id }}">

Json

Json inputs can be composed in a couple of different ways.

Input construction

With this method we will construct json with multiple input fields. We also need to define the type of the field for the json constructor. Type is given just before the parameter name. In many cases parameter name may represent the xpath in json, like string.inner.name will result in {"inner":{"name":""}}

Omitting key definition after the dot will result in setting input value as a root object to the json body.

Supported values

string - result: ({"name":"foo"})
number - result: ({"name":123})
boolean - result: ({"name":true})
json - result: ({"name":{"foo":"bar"}}). Allows to set any json structure.
delete - (special case to delete entire path from the json, value of the input would be ignored because only path is needed)

<input type="number"
       name="PricingApi.Api.Json.createPriceList.string.name"
       value="myTestVal">