Use bindings to supply additional information to a query at runtime. In this example we have

• An API endpoint that accepts a status field to filter a list of applications

• A query named applications

• An application that supplies data to the bindings of the query

Creating a binding

We can create a binding named status with a default value of all.

Using a binding

Using handlebars the binding can be referenced throughout the query in the following places:

• URL

• Params

• Headers

• Body

• Transformer

Params example

The binding can be used as the value of a param of the same name. While the name can be shared it is not required.

Headers example

The binding can be used as the value of a header of the same name. As above the binding and header name may or may not be shared.

Body example

The binding can be used in any part of the request body. e.g. as the value of a json field.

Supplying data to a binding

In our application we have the following structure:

Form: Status Form

The form that will hold the value of our selected status. This is the top level component so that the value can be accessed by components nested underneath.

• Type: Create

  • While this form does not create anything, this option is required to indicate that the input schema (the bindings) should be used rather than the schema returned by the query.

  • Update may also be used to the same effect.

• Schema: applications

  • The input schema of our REST query

Options Picker: Picker

We use an options picker in the form to provide our possible status values.

• Field: status

• Adds the selection to the form under the name status

• Options source: Custom

  • Custom options are specified using the Define Options drawer

Data Provider: Applications provider

We use a data provider to run the REST query

• Data: applications

  • The REST query

To link the query bindings to the form we use the bindings drawer

The value of the binding is {{ Status form.Fields.status }} which represents the status field in our form.

Conclusion

We are now able to:

• Specify a binding used in a REST query

• Specify where the value of that binding will be used using handlebars

• Create an application that supplies data to the binding and runs the query

The REST datasource is a powerful integration in Budibase that allows you to connect to data over HTTP.

Creating a new REST datasource

To create a new REST datasource use

• Data>Sources>Add>Rest>Continue

Configuration

Add additional configuration to your datasource in the form of queries, default headers, authentication and variables. Use the Save button when you have completed your changes.

Name

By default the REST datasource will have a name like REST or REST-1, you can change this to something recognisable if desired.

Queries

A query is an individual request in the rest datasource. Either create one from scratch or import an existing. For more details see:

Headers

Default headers that will be added to every query in the datasource.

Authentication

Configure authentication strategies that can be added to queries in the datasource. For more details see:

Variables

Create static or dynamic variables that can be used in queries in the datasource. For more details see:

Additional Operations

Use the navigator to perform additional operations on queries

• Delete

  • Delete the query

• Duplicate

  • Create a copy of the query

The REST query import feature allows you to import one or more queries at a time.

Import Formats

The supported formats for import are:

• Swagger 2.0 / OpenAPI 2.0 (yaml or json)

• CURL

Import Sources

URL

Enter the link to your API documentation.

File

Upload a file containing your API documentation.

Text

Enter the documentation string directly.

When the import completes the new queries will be displayed in the datasource

Import into a new datasource

To import queries into a new datasource use

• Data>Sources>Add>Rest>Import

Import into an existing datasource

To import queries into a new datasource use

• Data>Sources>Select REST source>Queries>Import

Authentication configs are specified at the datasource level and can be selected from queries within the datasource. Adding authentication to a datasource allows queries to run well known authentication strategies and can reduce the amount of configuration needed when multiple queries share the same authentication.

Datasource Configuration

A REST datasource can contain multiple authentication configs of well known types.

• Multiple configs of the same type can exist

• Configs must have a unique name

The appropriate information is added to the request when authentication is selected.

• Basic Auth

  • Adds the Base64 encoded username and password to the Authorization header

• Bearer Token

  • Adds the token to the Authorization headed as Bearer token

Query Configuration

From within a query use the Auth dropdown to select the desired authentication config to be added to the query.

Variables are a useful way to reuse data across REST queries. Variables come in two forms; static and dynamic.

Static Variables

Static variables store data that does not change. These can range from constants used in the metadata of the request to information about the request itself that can be used in the URL such as API version or hostname.

Variables nested inside other variables will not be evaluated.

Dynamic Variables

Dynamic variables provide a way to chain data between queries.

• Response data from one query can be used to create a dynamic variable

  • Header

  • Body field

• The result of the variable will be cached for a short period of time

• A variable will be re-evaluated if a query using it fails, in which case the query will retry once

• A query will fail if a variable cannot be evaluated

Header Variables

Use the ... menu alongside response headers to select Create dynamic variable

Give the variable a name.

• The name must be unique

• The name will be used to bind this variable in your query. e.g cookie can be used as {{cookie}}

The variable will appear in the Dynamic Variables tab

Body Variables

Use the ... menu alongside schema items to select Create dynamic variable

Give the variable a name as above

The variable will appear in the Dynamic Variables tab

Editing Dynamic Variables

In the above example we can see the user_id variable is bound to {{ data.0.[user] }} which is an object. To access nested data in the response body we can update the variable expression to reference the nested fields using dot notation e.g. {{ data.0.[user._id] }} .

Alternatively a query transformer can be used to update the schema so that the desired field is exposed in the schema directly.

Dynamic variables can also be created manually using the Add variable button.

• Access header data using {{ info.headers.[header-name] }}

• Access body data using {{ data.0.[body-field] }}

Using Variables

Once a variable has been defined it can be used in the exact same was as a binding.

• For example a variable named my-id can be referenced in the headers, params or body of a query using {{my-id}}

• For more details seeUsing a binding

Creating a new request

First, create a REST datasource if you do not have one already. For more details, see:

Use the Add query button to open the query editor.

Name

Give your query a recognizable name that will appear in the datasource navigator. For example, a query that retrieves a list of applications could be called applications.

URL

Enter the URL of the API endpoint you are using. The URL is the requested resource including the protocol, domain name, and path.

Method

Select the HTTP method used by the API endpoint you are using.

• GET retrieves data from an API.

• POST sends new data to an API.

• PATCH and PUT update existing data.

• DELETE removes existing data.

Access level

Select the access level required by the logged-in end-user. If the user visits a page where a query is executed and the access level is beyond the scope of the user's access the query will not run.

Params

URL parameters can be configured in the params tab.

• Parameters are appended to the end of the request URL, following ? and listed in key value pairs, separated by & using the following syntax: ?status=all&other=value

Bindings

For more information on using REST bindings see:

Headers

Use headers to supply key-value pairs accepted by your API.

• Switch the Active toggle to off to prevent the headers from being sent while keeping it's configuration.

Body

Use a request body to send information to an API endpoint.

• The Content-Type header will automatically be set when using:

  • raw(JSON) / application/json

  • raw(XML) / application/xml

  • raw(Text) / text/plain

• If you manually select a Content-Type header, that value will be overridden by the body type

Transformer

Transformers can be used to augment the format of the returned data.

For more information on using query transformers see:

Authentication

Preset authentication strategies configured at the REST datasource level can be used to authenticate queries.

For more information on using REST authentication see:

Sending the request

When your query is crafted you can use the Send button to preview the results of your query. When your query has been successfully executed you may save the query using Save Query

Using response data

When a query has run successfully the response data can be actioned on to better fit the usage in your application.

Modifying the schema

The response schema may be updated by:

• Adding or removing fields

• Changing the data type used when displaying the result in tables

Creating dynamic variables

The response schema and headers can be used to create dynamic variables

For more information on static and dynamic variables see: