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