Get started for free
Features
Database and API-builderVisual developmentIntegrations
Why Directual
For developersFor product ownersFor freelancers and agenciesFor startups
Resources
PricingBlogAcademyDocumentationForum
Legal
Terms of servicePrivacy policy
Directual Academy
Learn the basics

API-builder basics

← Back to the list of tutorials

API-builder the basics

An API, or application programming interface, is a gate between the back and front-end of an app, or between the back-end and a third party system.

Basically, an API-method is a URL — an Internet address through which we can write and read data to or from our database. We make a request and get a response from the API. Web pages, mobile apps or any other IT-system can use that same request and response process.

There are two options for setting up API-methods on the Directual platform:

  • Webhooks;
  • API-endpoints.

Webhooks

The simplest way to write data into the Directual cloud database is to use Webhooks. Many different services provide users with an integration method like that. For instance, Typeform, Webflow or Tilda. To create a Webhook URL, we go to the API tab, select ‘Webhooks’ and click the “New” button.

The data structure for it is created automatically in the “Integrations” folder. Now we have a webhook-method available for writing our data. Often, the data object comes in JSON-format. To handle it, we’ll use Directual scenarios. Through these steps, you can parse any JSON-data to the relevant objects and fields, and then, work with them in the normal way.

API-endpoints

A flexible technique for setting up API is called Endpoints. It supports GET- and POST-requests to read and write data. We can also configure user-based security, filtering, validation and other parameters.

Let’s set up an API-endpoint on Directual. Firstly — we choose the data structure we want to work with. As an example, let’s say it’s a structure containing information about books. Fill in the name of the request and a description, which helps teams to manage a high number of endpoints.

Then— we set up the security layer. First we choose the fields that will be available for requesting. A ‘GET-request’ reads the data, and a ‘POST-request’ writes the data. The linked objects can also be included in the API-response as well.

The security layer has a section with conditions for a user’s session. It defines the user-based security rules. While composing a condition, we pick one of the object fields from the “App users” structure (that’s the data structure where all your registered app users are stored). Then, fill-in the value for comparison. We can choose any other relationship between them, they can be equal or either one more or less than the other.

One layer might contain several conditions, united by the logical “And” or the logical “Or”.

The default rule “ID is not null” prohibits access by non-authorised users. Remove this condition if you want your data to be open to the public.

Next section is filtering. Here we can configure conditions, similar to ones we just considered. But there is one significant difference. We composing the conditions on the objects from our target structure, not from “App users”. In our book-related example we can filter all the books issued before 1950.

One very useful tool for checking the API-endpoint that we’re configuring is called, “Respond preview”. We can see the request. This parameter (the app ID) is also called the API key. This is a unique key to your application and we can see the response in JSON-format. Right here we can chose an “App user” from its ID, or create a new one. This allows us to see the respond when there are specific, user-based security rules. Note that a new request parameter just appeared — user session ID.

There’s one more basic tuning method for GET-requests — sorting. We can choose the field for objects sorting in the respond and sorting directions.  If we add more than one parameter, they will be applied one by one.

POST-requests will create or update objects. It hold on to the data in JSON-format. Remember, any fields that we send should be added in the Security layer. Otherwise we’ll get an ‘exception’ response.

We will cover advanced techniques of working with API-builder int the next video.

← Back to the list of tutorials

Have questions? Visit our community forum.