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

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

Most companies already have big databases that they want to pull data out of and use in their internal applications. Let's take a look at how we can connect to one.

Connecting to the database server

We will start by creating a new datasource. Click the + button next to the sources heading in the sidebar on the left. Enter a name for your connection and select the SQL source of your choice. In the example below we'll be using Postgres.

Once created you will be presented with a new screen. where you will have to enter your connection information. Enter the relevant information; host, port, database name as well auth information. Once you're done. Hit Save. If successful you will get a notification confirming that your datasource has been updated.

Fetching tables

To fetch the tables from your database click the Fetch tables from databasebutton. You will be presented with list of all the tables. Before veturing forth, update the display columns so that they make sense by clicking the button.

Creating relationships

To help Budibase understand your database you will need to create the relationships. In our example we have products that are related to our tasks via many-to-many relationship. Let's take a look at how something like that would look:

Through/join tables are only for many-to-many relationships in SQL.

If you have a direct mapping of 1:N with a foreign key you do not need a through table if you have a foreign key. To set up a relationship select One and link to the other table. Select the foreign key.

Writing your own Query

There are situations where you need more than a simple CRUD interface. In order to around that we also have the ability to write our own SQL queries. To get started, hit the Add query button. On the next page you will have to enter a name for the query as well as select the function you want to perform and last but certainly not least, enter your actual actual SQL.

After writing your query, hit the run query button. If successful you will be presented with a JSON schema. Click the Schema button and select the appropriate data types for the different fields. When you are satisfied with the query, hit Save Query.

Below you can see a list of available datasources. The way you connect to and use them differs a bit so in the next we sections we will explore them in more detail.

This datasource is the one that is native to Budibase. Any data you add here is stored directly on your Budibase instance.

Creating a table

Creating the table itself is pretty straight forward. Go ahead and enter a name.

Next up you have a number of "Auto Columns" you can pick and choose from. These columns will tell Budibase to add some extra information when new records are added or updated.

For example, selecting Created by and Updated by will add data to your records who created or updated the record is. Selecting Created at and Updated at will show you when a record was created and updated. The Auto ID option will add an auto incrementing ID column to your records so you can keep track of them more easily.

There's also a Generate screens in Design section option. Selecting this will auto generate screens in the front-end. We will talk more about this when we get to the Design section.

Importing Data

If you already have some data in the form of a CSV you can upload one here. Let's take a look at that. If you want to play around with a sample you can go ahead and use the one that has been added below.

When you have uploaded your CSV you will be presented with a number of new options. One for each column. It will look something like this:

Before you create your table you need to select what types each column should have. At the moment you can select between Text, Number, Date, Option and Boolean. It's very important that you select the correct thing here as the type is what determines much of what you can do with it later on in the Design section.

As only you know what your data looks like you will have to pick what makes sense here. Text is generally used for things like descriptions, long-form content, IDs containing letters among other things.

Number is a type that you should use when working with numbers; sales numbers, number of items in some inventory, revenue, profit, etc.

Date is for things like date of sale, shipping dates and so on.

Options can be used when you want a user to be able to pick between a number of different options. For example. In the Sales CSV that we imported above there's a Sales channelcolumn. It has two options: online and offline. When a user wants to add a new sale, this will allow them to pick between these two options rathern than type it in manually - much less error prone.

Picking something that does not make sense will result in a warning next to the column.

Adding or Editing Columns

Once you have imported or created a table you see it added to sidebar on the left under Sources. If you want to add or edit new column types you can do so by clicking the Create column button or by hovering on one of the already existing columns and clicking on the small edit button that appears.

Datatypes

When creating a table from scratch (not importing) you have access to some extra datatypes such as attachment, Long form text, Relationship, Formula and Auto Column. We explore these in more detail on the Data types page.

Adding data

Adding data is simple. click the Create rowbutton and you will be presented with a modal. Fill in all the data and hit save. If you set up your column types correctly when you created or imported your table you will now see the correct controls here. A date picker, option picker, etc.

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

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.

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

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:

Under construction.