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">

Header

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

1. string - result: ({"name":"foo"})
2. number - result: ({"name":123})
3. boolean - result: ({"name":true})
4. json - result: ({"name":{"foo":"bar"}}). Allows to set any json structure.
5. 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">

This sample would generate a json object like this

{
  "name": "myTestVal"
}

Adding multiple fields

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

This sample would generate a json object like this

{
  "name": "myTestVal",
  "start": 1000
}

We can also define nested field

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

This sample would generate a json object like this

{
  "name": "myTestVal",
  "test": {
    "start": 1000
  }
}

When one of the fields is of type array

<input type="text"
       name="PricingApi.Api.Json.myCall.string.name"
       value="myTestVal">
<input type="number"
       name="PricingApi.Api.Json.myCall.number.start.0"
       value="1000">

This sample would generate a json object like this

{
  "name": "myTestVal",
  "start": [
    1000
  ]
}

The number indicates the index of the array, knowing this we can construct the input with specific indexes

<input type="text"
       name="PricingApi.Api.Json.myCall.string.name"
       value="myTestVal">
<input type="number"
       name="PricingApi.Api.Json.myCall.number.start.0"
       value="1000">
<input type="number"
       name="PricingApi.Api.Json.myCall.number.start.1"
       value="1001">

This sample would generate a json object like this

{
  "name": "myTestVal",
  "start": [
    1000, 1001
  ]
}

Creating an array of objects to input.

<input type="text"
       name="PricingApi.Api.Json.myRequest1.string.code"
       value="myTestVal">
<input type="number"
       name="PricingApi.Api.Json.myRequest1.string.pairs.0.name"
       value="1000">
<input type="number"
       name="PricingApi.Api.Json.myRequest1.number.pairs.0.value"
       value="1001">

This sample would generate a json object like this

{
  "code": "myTestVal",
  "pairs": [
    {
      "name": "1000",
      "value": 1001
    }
  ]
}

Set entire json as a root object:

<input type="hidden" name="CaFaApi.Api.Json.putConf.json." 
       value='{"code":"test","name":"Foo","numbers":[1,2,4]}'>

Will generate payload like this:

{
  "code": "test",
  "name": "Foo",
  "numbers": [1, 2, 4]
}

Json input manipulation options

Starting from version 1.201.1, GoErp allows to make json modifications more flexible, like predefined json, connecting json parts from another request and many more. Check how it works with CAFA sample.

Raw

To send some custom data to the api endpoint that does not use a specific format (json, post params etc). Note that the key name here is not important (myCustomData) and it will not be used in the request.

<input type="hidden" name="AutomatApi.Api.Post.myRequest1"
       value="v5/some-endpoint">

<input type="hidden" name="AutomatApi.Api.Raw.myRequest1.myCustomData"
       value="custom-data">

Franchise

Usable for franchise accounts. Where the HQ account can make calls against certain stores. Note that the user on the HQ account needs to have access to the specified store through the multi account users feature.

<input type="hidden" name="AutomatApi.Api.Get.myRequest1"
       value="v2/local-application" data-preset-val="v2/local-application">

<input type="hidden" name="AutomatApi.Api.Franchise.myRequest1.clientCode"
       value="104373" data-preset-val="104373">

Using the value here will run the api call against that specific franchise account store.

Cache

Can be used to speed up page loads by caching certain api calls that do not use any parameters and are used mostly to fill selections. Items will be stored against the session and will refresh automatically within 1 hour (this can be altered with the duration parameter).

Define the cache key with a value of 1 to use the cache features. Adjusting the value to 0 or removing the key will disable the feature.

<input type="hidden" name="AccountAdminApi.Api.Get.timezones"
	 data-preset-val="v1/timezone">
<input type="hidden" name="AccountAdminApi.Api.Cache.timezones.session" data-preset-val="1">

Refresh cached results

Send the following parameter once to refresh the cached content for that request

<form method="post">
    <input type="hidden" name="AccountAdminApi.Api.Cache.timezones.refresh" value="1">
    <button type="submit">Refresh timezone cache</button>
</form>

Set custom duration

Optionally you can set a different duration for the cached elements (in seconds). This works together with the cache parameter and needs to exist when the data element is created.

If this value is not provided then the data will be cached by default for 3600 seconds.

<input type="hidden" name="AccountAdminApi.Api.Cache.timezones.duration" data-preset-val="7200">