API Best Practices

Overview

Configurators use API calls to process data in various ways. Remote executes keep data safe, improve speed and security, and keep proprietary processes hidden.

Applications with remote execute have endless opportunities. Follow these API best practices:

Organize configurations.

Standardize configurations so others can understand the purpose of the API call.

Enable use of the Unqork Development Life Cycle Toolkit.

What You'll Learn

In this article, you'll learn how to:

Create an API module.
Configure your API call.
Test your API call.
Use the Life Cycle Toolkit.
Handle errors in API calls.

Creating Your API Module

When you create a new module to build an API, keep these best practices in mind:

Include notation in the title indicating that this is an API module. A common convention is APPLICATION NAME: MODULE NAME (API).

Add the api Tag to your module.

Open the Settings for your module and set the Server Side Execution Only toggle to ON. The Preview button in the Module Builder displays as Server-Side Execution.

Using the API Specification Snippet

The API Specification snippet simplifies building an API in Unqork. It offers a standardized layout for modules that execute as APIs. Your API module stores in the API Docs Dashboard tool when you use the framework of this snippet. The API Docs Dashboard tool lists the API modules in your current environment and contains documentation for each API module. This documentation includes a description of the API and the request and response parameters.

To add the API Specification snippet to your module:

In the left sidebar of Module Builder, click the Snippets button.

In the search bar, enter API Specification.

Drag and drop the API Specification snippet onto your canvas.

Hover over each of the panelInfo, panelRequest, panelConfig, and panelResponse Panel components.

A 5-button toolbar displays above the component on hover-over.

Click and drag the

(Move) button, dropping each Panel outside the panelAPITemplate Panel component. This improves module performance.

Hover over the panelAPITemplate Panel component.

Using the toolbar, click the

(Remove) button.

Here's how the API Specification snippet looks in the Module Builder:

API Specification Snippet Best Practices

This article focuses on using the API Specification snippet to configure API modules using Unqork's best practices. For other configuration best practices, visit the Resources section.

Here's a breakdown of best practices for each panel in the API Specification snippet.

Only use the API Specification snippet for new API calls. For best results, do not create an API call from scratch.

panelInfo Panel

This Panel component is for the description of your API module. This information displays in the API Docs Dashboard to identify the API module's purpose.

Use the HTML Element component to write a brief description of your API module. For example, if your API module calls a weather API, you can enter: This module connects to a weather API to retrieve the current weather for a given zip code and country.

This Panel component also includes a Hidden component called method. Use this Hidden component to enter the module's specific HTTP method. By default, the component has the Default Value of GET/PUT/POST/DELETE. Edit this value for the method that applies to your API module. For example, if your API module gets weather reports, set the Default Value to GET.

panelRequest Panel

This Panel component is where you define your request parameters. By default, the Panel contains a single Hidden component for a request parameter. Add and configure one Hidden component for each request parameter needed. If the API call doesn't have any request parameters, you can leave this Panel empty.

Configure each Hidden component according to these best practices:

Setting	Description and Configuration
Property ID	Enter the name of the parameter as a camel-case string.
Required	If the parameter is required, set the Required toggle to ON.
Store Data in Database	This setting determines whether the parameter is included in the response. Ensure the Store Data in Database toggle is set to OFF. Doing so avoids request parameters from being returned.
Field Tags	Set the data type for the parameter. The component comes preset with all available tags. Delete all tags that you don't want to apply. The available tags are: type:string: If the data type is an alphanumeric string. type:number: If the data type is an integer or a float point number. type:boolean: If the data type is Boolean (true or false). type:array-string: If the data structure is an array containing a string data type. type:array-boolean: If the data structure is an array containing a Boolean (true or false) data type. type:array-number: If the data structure is an array containing an integer or a float point number data type. type:object: If the data structure is an object. type:ObjectId: If the data is a MongoDB unique identifier. The type:array Field Tag is the same as the type:array-string Field Tag.
Notes	In the Notes section, enter a parameter description. Make sure to click the Note's Save button after you enter the description.

panelConfig Panel

This Panel component is where you add the API configuration logic. This includes a Plug-In, Initializer, and any other components you need to complete your API configuration. Nothing in this panel is persistent, so each component's Store Data in Database toggle is set to OFF.

By default, this Panel comes with a preset Decisions component to configure HTTP response codes. This component lets you manually set up the response codes you want produced by the API call. This configuration is especially helpful to alert you when a call fails.

To learn more about HTTP Output response codes, visit our HTTP Status Codes article.

panelResponse Panel

This Panel component is where you define the response parameters. By default, the Panel contains a single Hidden component for a response parameter. Add and configure one Hidden component for each response parameter needed. If the API call doesn't have any response parameters, you can leave this Panel empty.

Configure each Hidden component according to these best practices:

Setting	Description and Configuration
Property ID	Enter the name of the parameter as a camel-case string.
Required	Setting the Required toggle to ON ensures the parameter is present in the response.
Store Data in Database	This setting determines whether the parameter is included in the response. Ensure the Store Data in Database toggle is set to ON so the parameter is included in the response.
Field Tags	Set the data type for the parameter. The component comes preset with all available tags. Delete all tags that you don't want to apply. The available tags are: type:string: If the data type is an alphanumeric string. type:number: If the data type is an integer or a float point number. type:boolean: If the data type is Boolean (true or false). type:array-string: If the data structure is an array containing a string data type. type:array-boolean: If the data structure is an array containing a Boolean (true or false) data type. type:array-number: If the data structure is an array containing an integer or a float point number data type. type:object: If the data structure is an object. type:ObjectId: If the data is a MongoDB unique identifier. The type:array Field Tag is the same as the type:array-string Field Tag.
Notes	In the Notes section, enter a parameter description. Make sure to click the Note's Save button after you enter the description.

A trigger executes the logic of a remote API. Avoid using the Watch Trigger Type in all logic components. Logic components include Calculator, Decisions, Plug-In, and Data Workflow components.

Testing the API Call

It is imperative that you test your configurations when you build in the Unqork Designer Platform, including when you build APIs.

Follow these steps to test your API call:

Test your application in Express View to see how the end-user experiences the front end of your application.

Use the Server Side Execution Testing page to test your API. The Server Side Execution Testing page is the best course of action when testing API calls that run on the server.

Run your API module as a remote execute, and reach your endpoint from wherever your application calls the API module. That way, you ensure your API call works as expected.

Using the Life Cycle Toolkit

The UDLC Toolkit (Unqork Development Life Cycle Toolkit) helps you organize and visualize your projects. Use the API Specification snippet to API modules to take advantage of the UDLC Toolkit. The success of these tools depends on following consistent best practices in your modules.

The API Docs Dashboard and the Config Analysis Dashboard tools rely on you following API best practices.

API Docs Dashboard Tool

The API Docs Dashboard tool shows a dashboard view of the modules connected to every API (application programming interface) and remote execute. The tool builds documentation for the module when you select one from the dashboard. This documentation includes API call descriptions as well as their request and response parameters. The data type and description of each field also displays when you select one of the modules.

Remote executes interface with a module via an API call instead of loading the module in the browser. You build an API endpoint that other modules in your application can use when you build a remote execute module. So, the term API module can refer to a remote execute module or a module with a basic API call.

Follow three best practices to make sure this tool works:

Add the api Tag to your module. This makes your module easier to find in the API Docs Dashboard.
Follow the API Specification snippet to help you build API modules. APIs work as intended when you use these guidelines, and their documentation displays in the dashboard. Plus, The use of this template makes your Unqork configuration more consistent.
Set the Server Side Execution Only toggle to ON.

Config Analysis Dashboard Tool

Also take note of the Config Analysis Dashboard tool, which analyzes best practices across a variety of metrics in the Unqork Designer Platform.

The Config Analysis Tool helps resolve complex issues that come up as you build in the Unqork Designer Platform. With this tool, Unqork provides feedback on your applications as you build.

Use the Config Analysis Tool to submit your configurations for review. The team at Unqork runs multiple tests on each configuration, and they suggest possible improvements. They also send you a detailed report from the tests, so you avoid similar configuration issues in the future. Upload your report to the Config Analysis Dashboard tool to filter and organize your information with ease. Track changes as you and your team update the project to see progress in real-time. The tool includes a variety of charts as visualization aids for the report. Use these KPI A quanitifiable measure of performance of a specific objective for a specified time. widgets to print, export, and share test results.

This tool lets you:

View a detailed list of the configuration analysis requests submitted in the current environment.
Submit new configuration analysis requests.
Upload a configuration analysis file.
View existing config analysis data.
Update violation statuses to see which violations are in review.

A Filters Panel displays when you use the Config Analysis Dashboard tool. Notice the 2 parameters dedicated to API best practices when you filter for tests:

getApiSpecViolations: Identifies the modules that execute as APIs but violate API specifications at Unqork.
getApiParamViolations: Identifies request or response parameters in remote execute modules that violate API specifications at Unqork.

Handling Errors in an API Call

Mistakes happen in configurations despite your best efforts. Practice configuring complex applications and troubleshooting errors to minimize mistakes over time. These API troubleshooting tips and best practices make error handling easier.

Error Handling for Remote Execute API Modules

API modules using remote execute can enable HTTP status code outputs. These status codes provide improved error handling for developers when testing or monitoring their API calls.

Errors Handling for Plug-in Calls

Every Plug-in component requires error triggers to handle configuration issues. These triggers alert you when a specific Plug-in breaks. The trigger sends you an error code associated with all API errors. The resulting status code helps you fix the specific problem instead of having to blindly troubleshoot API calls.

Error Handling and Troubleshooting

You can find more information about error handling in the Expert Integration Troubleshooting and Introduction to Error Handling courses through Unqork Academy.