Improvements on API Builder

Context

Currently, if any customer needs to create a custom API that works over custom Objects, they have two options:

• use the default API generated with the Object (one API for each object).
• develop it on top of REST builder (using a partner or it’s own IT department).

The same applies if you need to create Custom Data Lists for Objects. Your only possibility is to develop it.

So, with the focus on this last use case, but with long term goal of providing full-fledge tool that can cover more complex use cases, we have developed the API Builder: a way to create custom API Applications with No Code.

What we have done

We have created a new application that helps developers to build APIs based on custom Objects in a No Code UI. This new feature allow users to define the whole structure of the API, from the endpoint’s name to the data model of the request and response schemes.

How it works

Although we are going to focus on the UI part, it’s very important to know that all capabilities are available at the API layer because the persistence layer of the API Builder is Objects and every object has it’s own CRUD API application created by default.

Objects & API applications:

• API Application
• API Endpoint
• API Schema
• API Property
• API Filter
• API Sort

You can find all the applications under /o/headless-builder/ path

Access to the API Builder UI:

> Control Panel > Object > API Builder

API Application:

Create API Application

Add new API Application

When user types the Title, the URL is completed automatically using lowercase letters and deleting the special characters except “-” . As stated in the modal, users can modify the relative URL of the API application if the need.

All new Applications are created as UNPUBLISHED by default

Once the application is created, users can see and modify the details of the application. Additionally, they will have access to two new tabs: Endpoints and Schemas. 

 

Edit & Delete

From the App’s list, the user can access directly to:

• Edit: direct access to the edit page.
• Delete: when the user clicks over this option, a confirmation modal is shown. The user needs to type the name of the App in order to confirm the delete action

Please note: Deleting an APP will delete all related elements (schemas and endpoints).

 

API Schema:

A schema always must be related to an application and could be related to one or more endpoints.

Creating a API Schema

• Name: the user decides the name of the schema
• Description: the user can add a description (not mandatory)
• Object: drop down list with the existing objects (system and custom). All properties added to the schema belong to the main object or its related objects.

Please note: this main object cannot be changed after creating the schema.

 

Edit & Delete

From the Schema’s list, users can edit or delete one of them. By clicking the edit option, the user navigates to the info tab at the edit page and, the delete option, shows a confirmation modal.

API Schema Properties:

Users can define the structure and the properties of the schema in the UI, using 2 different areas:

1. Schema structure: in this area, users can order the properties, search for them and see the whole structure of the schema.
2. Properties from the main object: in this area, users can select the properties to add to the schema just clicking over them. Apart from the main object properties, if it has any related object, the button “View Related Objects” will be shown.

Adding a property to the schema:

When you hover any property, a "+" icon is shown and, clicking on the name or on the icon, the property appears at the top of the properties inside the area 1. If the user wants to add a property from a related object, they can use the View Related Objects button and navigate to the appropriate property.

The “search” of the properties only looks for properties inside the object that is selected.

A property can be added only once to a schema. Once it is used, it will become disabled in the object’s properties list.

Edit a property of the schema:

Hover the property in the schema structure so an edit icon is shown and, by clicking it, a modal is shown

• Name: label that will be shown at the schema definition
• Description: description of the property (not mandatory)
• Data type: type of the property of the object (cannot be changed)
• Mapped property: field of the object that is mapped to the schema property (cannot be changed)

Delete a property of the schema:

Hover the property at the schema structure, a delete icon is shown and, by clicking it, the property is deleted from the schema and is enabled again in the object property list.

API Endpoint:

Please note: An endpoint always must be related to an application.

Creating an API Endpoint

To create a new endpoint, the user only needs to complete 2 fields: Scope ( Company or Site ) and the Path. Later, when the endpoint is created, user can select the related schema for the response at the configuration tab:

and adding the pre-filter and sorting using OData queries:

• Filter example: name eq ‘Mary’
• Sort example: name:desc, surname:asc

To create the pre filter and sorting, you need to type the OData sentence using the name of the object field, not the name of the property at the schema. And you can use any object field that is not included in the Schema definition.

Edit and Delete:

From the Endpoint’s list, users can edit or delete them. By clicking the edit option, the user navigates to the info tab at the edit page and, the delete option, shows a confirmation modal.

Deleting an Endpoint doesn't delete the related Schema

Publish and Unpublish API applications

Currently, API applications can be in one of two states : Published and Unpublished.

• Unpublished: It’s the default state of the application when it’s created. In this state, the app is not available for other systems and it’s not visible in the Headless API Explorer.
• Published: If all validations are correct, the app is available and accesible to other systems and it’s visible in the Headless API Explorer. The Path will be https://{host}/o/c/{app_path}/

Users can change the status any time they need it. Only when the change is from Published to Unpublished, the user will see this confirmation modal:

There is no draft option so, if the app is Published, any change in the app, schema, endpoint, etc, will be available immediately. Users can update the changes clicking the Publish button on the UI or via API.warning text here

Once the App is completed with the endpoints and schemas, and it’s published, the new API Application will be shown in the API Explorer and will be available for use from any other application that may need it.

Demo & Additional Resources

Limitations

In this first MVP, only GET endpoints can be created and the structure of the schemas is flat (no possibility to create complex hierarchies between properties)

Next Steps

• Possibility to create PUT, POST, PATCH, DELETE and GET single element methods.
• Possibility to use complex hierarchies (containers) inside schemas:

  • Single Element

  • Array Element