Cloras API Manager

The Cloras API Manager provides a user-friendly template to add, edit, manage and store n number of system APIs. The APIs that are added here are later used in Flows and Mapping.

The components that support making successful API Calls to the target system include:

  1. Method

  2. URL

  3. Headers

  4. Params

  5. Body

The following sections describe how each of these parameters are utilized in the API Manager.

Cloras API Manager in only intended to manage APIs. The API is expected to be available in the respective systems. Adding an API here will not create the API in the respective system.

Add new API

To manage a new API, click on "Add New" in the API manager page. A new window will open and this is where you will define parameters and other details for your API.

General

  1. Name: Provide a suitable name for your API. Example: Magento2 Update Customers, P21 Get Customer Info, etc.

  2. Status: This is a toggle ON/OFF button that allows you to enable/disable an API

  3. Select system: Select a system from the drop-down list. This is the system with which the API is associated.

    Example: Epicor P21, Magento

  4. Override Timeout: This is a toggle ON/OFF button that lets you choose between custom/default "maximum allowed time" values, before which a Timeout error is thrown.

    1. Override Timeout ON: Once the Overrride Timeout is set to ON, two fields- Connect and Read- are displayed. You may set a time (in seconds) in both these fields.

      • "Connect" refers to the maximum allowed time for Cloras to establish communication with the system to which the API call is made.

      • "Read" refers to the maximum allowed time for the system to respond back to Cloras.

      Users can enter only 4 digit numeric values in the Connect and Read fields.

    2. Override Timeout OFF: Setting the Override Timeout to OFF, will consider default values for "Connect" and "Read":

  • Default value for Connect = 30 seconds

  • Default value for Read = 240 seconds

Add API - General information

API Connection

Three fields are set for each parameter/header/body:

Field

Description

Label

A suitable display name for headers/params/body data

Key

Variable name at which the value is populated

Value

The actual value stored in the Key

Example

  • Label: Content-Type

  • Key: Content-Type

  • Value: Supported Content Types

    • application/json

    • application/xml

Following are the components that are required in making successful API Calls to a system:

Bulk Edit

The Label, Key and Value details for a parameter or header can also be added as raw data in the following way. Click on the Bulk Edit button and enter the data as colon separated entities as shown below:

label::key::value

Content-type::Content-type::application/json

Authorization::Authorization::OAuth

Request Methods

Request Methods specify the action to be performed by an API call, on a resource. Choose from the drop-down list.

For more information on Request methods click here.

Relative URL / Endpoint:

The endpoint is the location or touch-point of communication, from which the API can access resources to carry out its functions.

Let's say you want to invoke an API call using a URL such as http://www.example.com/api/customers.

Here, the host-name www.example.com is provided in the credentials section in the Projects Area. So only the relative URL /api/customers needs to be provided here.

Some examples are

<GET> /api/customers/{customer_id}
<POST> /api/customers
<PUT> /api/customers/{shipping_id}/editshipping

In an API call, URL arguments and query parameters can also be sent. These are defined in the 'API Call' handler in Flows.

Use Case - URL Arguments

Let’s say, you want to make an API call with dynamic values in the URL like http://www.example.com/api/customers/2. Here, 2 is the dynamic value. This can be achieved by replacing the dynamic value with a unique variable name and this value will be provided in Flows during run-time.

The Endpoint provided in the API Manager will be: /api/customers/{customer_id}

In order to assign the dynamic value, enter {"customer_id":"2"} in API Call Handler in the URL Arguments box. The Endpoint will then replace the URL argument as: /api/customers/2, which indicates that information from customer_id = 2 is accessed.

Params

Query parameters are also assigned in the API Call handler in Flows. Let’s say, you want to make an API call with query params in the URL like /api/customers/?format=json

The Endpoint provided in the API Manager will be: /api/customers and the query parameter defined in the API Call handler is {"format":"json"}.

The Endpoint will then include the query parameter.

Setting URL arguments and params in the API Call Handler

Headers

Header data are passed as part of an API call.

Commonly used Header data include:

  1. Content-Type

  2. Accept

For more information on Headers please click here.

Request Body

JSON objects that are sent along with a POST or PUT request, to create/ update a resource. Body parameters are dynamic data, usually assigned in the Payload section of the API Call handler in Flows.

Setting Body data in the API Call Handler

Request and Response

The Request and Response sections contain sample JSON data.

The keys given in this JSON sample are displayed as fields in the Mapping area Source and Destination sections to enable mapping.

The sample request and response fields are optional (but recommended) in the API Manager. If no data is entered here, then the Source and Destination fields will be empty in the Mapping configuration page.