API Management allows you to create API collections and endpoints. Using these, you can create API calls that execute the callable journeys in the backend in just one click. Let’s drill down through this document and learn how to create a sample API endpoint using API Management.

Prerequisites

API endpoints can be created for Callable Journeys only. Ensure you have a Callable Journey created and running before creating its API endpoint. Click here to know more about Callable Journey.

Terminology

To create an API endpoint using the API Management feature, it is important to understand its terminologies.

API endpoint host

API endpoint host is the base path to which multiple endpoints are appended. The API endpoint host is https://apim.quickwork.co/. It is static in nature and is pre-created by Quickwork. Contact our support team to get a custom domain of your choice as an API endpoint host.

Path prefix

Path prefix is a user-defined unique identifier used to identify for which account the API endpoint is to be created. It could be alphanumeric characters. The path prefix appends to the static API endpoint host e.g., https://apim.quickwork.co/path_prefix.

API collections

API collection is a set of endpoints that can be managed together. It has a specific path that is to be defined while creating an endpoint. The API collection path appends to the path prefix e.g., https://apim.quickwork.co/path_prefix/api_collection_path/v1.

API endpoints

API endpoint is the path to the action within the resource for which you want to create an API. It is the journey that you want to call upon hitting the endpoint. The API endpoint appends to the path prefix e.g., https://apim.quickwork.co/path_prefix/api_collection_path/v1/api_endpoint.

Clients

A client is a user for whom you want to create an API endpoint. The client offers an API key using which the API endpoint can be executed. A single client can have access to one or more API Collections.

Access profiles

There can be one or more access profiles for a single client. Each access profile has a unique API key and policy as per which the usage of the API endpoint is decided. Clients can access one or more API collections through the access profile as per the access policy designed for them.

Access policies

An access policy defines the usage, permission, and restrictions of the API for a single access profile. A single access policy can be associated with one or more access policies.

Getting started

Let us create an API endpoint for a sample Callable Journey, Get Card Details. Go to the Tools menu and click the API Management.

Creating a path prefix

If you are using this feature for the first time, you’ll get a blank window asking to create a path prefix. Enter the path prefix, say cli, and click the Save button:

As soon as the path prefix is created, you’ll get a confirmation message and three tabs will get displayed on the API Management window:

1. API collections

2. Clients

3. Settings

The created path prefix can be viewed in the Settings tab. You can create only one path prefix for all the API collections and endpoints. The created path prefix cannot be edited or deleted.

Creating an API collection

Now, let us create an API collection that can store callable journeys as the official API endpoints. Switch to the API collections tab and click the + Create new API Collection button:

A form-like window will open with the following input fields:

1. Name: The name of your API collection. E.g., HRMS.

2. Version: The version number of the API collection. E.g., v1.

3. Description: The additional information about this API collection.

4. Path: The path of this API collection. E.g., hrms. This path along with the version number will append to the static API endpoint host:

As soon as you specify the path, a dynamic endpoint gets displayed down under as highlighted in the screenshot. This link is comprised of path_prefix/api_collection_path/version_number.

Click the Submit button. The API collection is now created successfully. However, it has no endpoints yet:

Creating an endpoint

Now, let us create an endpoint for the Get Card Details callable journey. Click the Hrms API collection. The window will appear as a blank canvas since there are no endpoints created. Click the + Create a new Endpoint button:

A form-like window will open with the following input fields:

1. Name: The name of your API endpoint. E.g., Get Card Details API.

2. Callable journey: The callable journey that you want to convert to an API endpoint. E.g., Get Card Details. The drop-down menu displays the name of the callable journeys that are in the running state.

3. Method: The method for this API call is as per the functioning of the callable journey. E.g., GET. The additional information about this API collection.

4. Path: The path of this API collection. E.g., card_details. This path will append to the API collection path:

5. Cors: Cors (Cross-Origin Resource Sharing) permits the loading of the API endpoints or other resources from a specific domain or a list of domains. An API endpoint will be permitted only if it has been called from the domain server specified in this field. E.g., https://quickwork.co. Specify * to allow this API endpoint to get called from any domain. Use a comma delimiter to specify more than one domain. E.g., https://quickwork.co,https://myjio.com, etc.

Now, click the Submit button. The API endpoint for the designated callable journey will get created successfully. The endpoint is https://apim.quickwork.co/cli/hrms/v1/card_details:

You can edit the details of this endpoint and can delete it permanently from the account.

However, this API endpoint is partially configured. If you call this endpoint through any API development platform such as Swagger, Postman, etc, you’ll get the authentication error as No API key found in request:

This means you need to authorize this API endpoint by specifying the access profile API key under the Headers section. After successful authorization, you can use the API endpoint to call the dedicated callable journey.

To get the API key, an access profile on the client-server is mandatory to build.

Creating a client

Switch to the Clients tab and click the + Create new Client button. Give a name for the client and Save:

You can rename and delete the client account. As you can see, there are no access profiles in this newly created client. Let’s create one.

Create an access profile

Click the client board and then click the + Create new Access Profile button. A form-like window will open with the following input fields:

1. Name: The name of the access profile. E.g., HRMS access profile.

2. API Collections: The name of the API collection that should be accessible to this client. You can select multiple API collections in a single access profile. One access profile can be used to access one or more API collections and their endpoints.

3. Description: The description of the access profile:

4. Rate limit: The limit you want to set for the access profile using which you want to call the API endpoint:

1. Time Interval: The maximum time interval for the access token. E.g., Per minute.

2. Number of requests: A total number of API calls to be triggered using the token within the specified time interval. E.g., 100.

The above-specified inputs mean, 100 times the API endpoint can be requested per minute. It can be set to days and months.

5. Usage quota: The number of times the client is allowed to use the API endpoint within the specified time duration.

1. Time Interval: The maximum time interval for the client to use the API endpoint. E.g., Per month.

2. Number of requests: A total number of API requests a client can make in a specified time duration. E.g., 20000.

The above-specified inputs mean, 20000 times the client can request for the API endpoint per month. It can be set to a year.

6. IP Whitelist: The IP(s) through which the API calls should be made using the endpoint. For example, if 172.217. 22.14 is the IP specified here, then API requests through this IP will be accepted. Rest all the IPs will be blocked who try to request the API endpoint.

Click the Submit button. You’ll get the API key as highlighted:

This window also displays limits set for the API key and API endpoint usage and the name of the API collections for which the access profile has been created.

Executing the created API

Copy the API key and go back to your API Development tool to test the created API https://apim.quickwork.co/cli/hrms/v1/card_details.

Select the method, i.e. Get and paste the API. Now, go to the Headers section. Specify apiKey under the KEY field and paste the API key value obtained under the VALUE field:

Now, click the Send button. You’ll get the response of the callable journey in the API Development tool exactly equal to the response obtained in Quickwork:

Sharing the API

It is possible to share the API with other users or customers. Simply share the endpoint and the API key generated in the access profile of the Clients window. Ensure that rate limit and usage quota are appropriately configured with proper whitelisting of IP addresses.