API Gateway

API Gateway

 

Introduction

An API gateway is an intermediate layer between the client and the server that acts as a reverse proxy and routes client requests to individual services. Catalyst provides API Gateway as an advanced API management tool that enables you to create, maintain, and monitor HTTP requests generated from client applications and microservices.

Catalyst API Gateway acts as a single entryway into accessing the following target components of your Catalyst application:

Once you enable API Gateway for your Catalyst project in the Catalyst web console, all client requests to access these targets will be handled by this gateway. This helps prevent these components from being directly exposed to the clients by decoupling the clients from services.

You can create customized individual APIs for every request type to access these targets. The API Gateway handles these functionalities of an API call and processes the request accordingly:

  • Routing
  • Authentication (optional)
  • Throttling (optional)

Catalyst provides API Gateway as an optional, paid component, and as an enhancement to Security Rules. While Security Rules provides basic routing and authentication features for your functions, API Gateway provides more flexibility in customizing the functionalities mentioned above for your APIs. You can learn more from the Security Rules vs API Gateway section.

You can also work with API Gateway from the Catalyst CLI. You can enable or disable it, and check its status. You can learn about this from the Working with API Gateway CLI help page. You can also pull the JSON file that contains the definitions of the APIs you create in your remote console to your local environment, and work on it locally. You can then deploy it to the remote console.

 

Key Concepts

Before you learn about API Gateway's architecture and implementation, it's important to understand its fundamental concepts in detail.

API Gateway vs Security Rules

Catalyst API Gateway is an enhancement to Catalyst Security Rules as it provides additional features for API management.

Points to remember:

  • You can enable or disable the API Gateway at any time.
  • When the API Gateway is disabled, the configurations defined for a Catalyst function in Security Rules will be followed by default.
  • When you enable API Gateway for your Catalyst application, Security Rules will be disabled automatically.
  • After you enable API Gateway, the URLs of your functions and web client will immediately become inaccessible until you create APIs for them. Therefore, if you enable API Gateway, you must create APIs for all your functions and web client.
  • You can migrate the configurations of your functions in Security Rules to API Gateway using auto-create.

The differences between Security Rules and API Gateway are specified below:

Security RulesAPI Gateway
Can configure access for GET, PUT, POST, DELETE, and PATCH HTTP methodsCan configure access for GET, PUT, POST, DELETE, and PATCH HTTP methods. Can also aggregate all HTTP methods under ANY, and create a single API for it.
Request URL and Target URL are the sameCan configure custom Request URL and Target URL separately. Can create individual APIs for each request method for every URL
Can enable or disable authentication and configure two types of authentication: Catalyst Users Authentication, and OAuth-based AuthenticationCan enable or disable authentication and configure three types of authentication: API Key, Catalyst Users Authentication, and OAuth-based Authentication
No throttling featureCan configure two types of throttling: General Throttling and IP-based Throttling
Cannot configure rules for web clientsCan create APIs for web clients
 

Routing

The primary purpose of an API Gateway is to route the client to the appropriate services. This is defined by two aspects of an API: Request and Target. If an API has not been configured for a particular request method or request URL, the client will not be able to access the target.

Let's learn about these in detail.

Request Methods

Catalyst API Gateway supports the following HTTP request methods:

  • GET
  • PUT
  • POST
  • DELETE
  • PATCH

You can also aggregate all these HTTP methods under a custom defined method: ANY. This enables you to create a single API for a function that supports all five methods, instead of creating five individual APIs, one for each method. ANY can be used both in auto-create and creating custom APIs.

Note: Web client APIs do not support ANY. You can only select the GET method for a web client.
 

Request URL

The URL of your Catalyst application has the following structure: https://project_domain_name.catalystserverless.com. When you create an API, you can define the request path and it will be automatically appended to this URL. This will be the request URL.

For example, if the request path is /CustomerPortal/create, it will be appended to the application URL of that project, and the following request URL will be created: https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/create.

You can then provide this intermediary request URL to the client, instead of the target function's or web client's default URL. The API that will then route this request URL to the configured target automatically.

Target and Target URL

As mentioned before, the target components of an API configured in API Gateway can be: Basic I/O functions, Advanced I/O functions, web client. You can set one target for every API that you create in API Gateway. You can create multiple APIs for each target for different request methods.

Note: API Gateway does not handle client requests for Cron Functions and Event Functions as they cannot be directly executed by end users.

The URL format of each target is as follows:

  • Basic I/O: https://project_domain_name.catalystserverless.com/baas/v1/project/project_ID/function/function_ID/execute
  • Advanced I/O: https://project_domain_name.catalystserverless.com/server/function_name/
  • Web Client: https://project_domain_name.catalystserverless.com/app/

You can append routes to an Advanced I/O function's or web client's target URL and create APIs for specific paths.

Using Regular Expressions (Regex) in the Request URL and Target URL

Catalyst offers support for regular expressions to hold dynamic values in the request URL. A regular expression (regex) is a sequence of characters that describes a search pattern. When you include a regex pattern in the request URL, pattern-matching, and search-and-replace algorithms are executed when the input value is provided during execution and the pattern is replaced with the dynamic value.

You can enter a regex pattern in the JSON format in the request URL and pass the key to the target URL like:
Request url:/route/{path:[0-9]+}
Target url:/route/{path}

For example, if the dynamic value of a request URL contains a string of numbers, you can use the expression [0-9]+. This indicates that the characters inside the brackets in the dynamic value can be any span of numbers from 0-9 and the + indicates one or more occurrences of the digits. Therefore, the request URL here could be configured as: /CustomerPortal/{portalID:[0-9]+}.Now, if you append a route to the target URL of an Advanced I/O function as: /server/adIOFunc/CustomerPortal/{portalID}, the ID provided by the user in the request URL while accessing it will be dynamically passed to the target Advanced I/O function.

You can also use a wildcard pattern in your regular expression, such as .* ,which indicates that any number of literal characters or an empty string can be accepted in the place of the wildcard pattern. For example, if you provide a wildcard pattern in the request URL like: /CustomerPortal/{path:(.*)}, the user will be able to enter any value dynamically in the URL such as: /CustomerPortal/johndoe12, /CustomerPortal/premiumUser/12809021, or /CustomerPortal/xae89013.

If you defined a regex pattern in the URL for an Advanced I/O function in Security Rules, the same pattern will be added to both the request URL and target URL during auto-create.

 

Authentication Request Processor

The Request Processor handles the authentication of the API. Authentication is an optional feature in API Gateway. If you select No Authentication while creating the API, the target will be universally accessible to every client.

Note: The authentication feature is not available for web client APIs. It is only available for the Basic I/O and Advanced I/O functions.

API Gateway supports three authentication methods. You can enable any or all of these methods.

API Key

This authentication is handled by an API key that is generated by Catalyst automatically for your project. The API Key is the same for all projects in the development environment. When you deploy a Catalyst project to the Production environment, Catalyst will provide you a different API key. You will therefore have individual API keys for each project in the Production environment.

You can obtain the API key after you create an API for a Basic I/O or Advanced I/O function in your project, with the API Key authentication option enabled. Click View API Key in the API details section to access the key.

A pop-up window will open with the API key.

You can pass the API key in two ways:

  • Request Header
    You can pass the API key as a header in the request URL as shown in this example:
    curl -X POST \
    					https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/create \
    					-H "ZCFKEY: API_KEY"
  • Query String
    You can also pass the API key as a query parameter in the request URL as shown in this example:
    POST https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/create?ZCFKEY=API_KEY

Replace API_KEY with your API key in both places.

Catalyst Users Authentication

This authentication method enables access for all the users of your Catalyst application added in the Users section of Catalyst Authentication, by default. You can handle this authentication method by incorporating a user sign-in form in your Catalyst application, and enabling a login session. The app users will then be able to access the API's target automatically without needing to go through any additional user verification.

OAuth-Based Authentication

This authentication method enables access for the users with an OAuth access token.

You can pass the access token as a header in your in the request URL as shown in this example:

curl -X POST \
			https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/create \
			-H "Authorization: Zoho-oauthtoken 1000.910***************************16.2f****************************57"
 

To implement OAuth authentication in your Catalyst application, refer to our OAuth Authentication help documentation for detailed steps.

 

Throttling

Throttling enables you to set a rate limit to control the usage of an API by the clients. Throttling is an optional feature in Catalyst API Gateway. When you set throttling rate limits for an API, Catalyst will monitor the count of request hits made to that API. When the request submissions exceed the limits you have configured for the API, the API Gateway will return the HTTP error response: 429 Too Many Requests.

There are two types of throttling available in API Gateway. You can use either one or both methods.

General Throttling

General throttling defines the maximum hits allowed to the API for all users, per time unit. You can define the request limit, its rate, and the time unit while creating the API.

Catalyst implements a sliding window rate limiting algorithm where the window starts from the current element and shifts by a weighted value of the previous window's request rate. For example, if you set 50 requests in 2 minutes as the limit, Catalyst will check for API hits in the 2 minutes preceding the current second and determine the count, instead of checking in a 2 minute fixed window length.

IP-Based Throttling

IP-based throttling defines the maximum number of hits allowed to the API from a particular IP address, per time unit. This limits the number of API calls that can be made from a particular client address. You can define the request limit, its rate, and the time unit for this in a similar way as for general throttling.

 

Auto-Created APIs, Custom APIs, and the Default API

You can create APIs for your Catalyst functions and web client in two ways: auto-create or custom.

Before we discuss auto-created APIs and custom APIs, you must learn about the default API.

The Default API

API Gateway creates a default API called Login Redirect for the web client hosted in your Catalyst project, in addition to the regular web client API.

The following rules apply for the Login Redirect API:

  • This API is created when you create APIs in the API Gateway for the first time after hosting a web client in your Catalyst project, using either auto-create or the custom method.
  • The Login Redirect API is created based on the configuration set in the client-package.json file for the web client. The URL configured as the login_redirect in that file will be set as the request URL and target URL of the API. The login_redirect key is optional. Therefore, if it is not configured, the URL provided as the homepage will be set as the request URL and target URL.
  • If the URL configured as login_redirect starts with a '/', Catalyst will consider it as an absolute path and will append it to the domain directly. For example, if login_redirect is '/home.html', the request URL will be of the format: https://project_domain_name.catalystserverless.com/home.html. However, if the login_redirect value does not start with a '/', such as 'home.html', then the request URL will be of the format: https://project_domain_name.catalystserverless.com/app/home.html.
  • The values for general throttling and IP-based throttling for this default API will be set to Not configured, and the value for authentication will be set to No authentication.
  • You must give the default login redirect page of the Catalyst application as the request URL for the Login Redirect API. You must not give any other URL as its value.
  • If you change the value of login_redirect in the client-package.json file after the Login Redirect API was created, the target URL value will be automatically changed when you deploy the client package to the Catalyst console.
  • You will not be able to edit any of these default values except the request URL. You will not be able to modify the target URL, API name, authentication, or throttling parameters.
  • You will not be able to delete the Login Redirect API.
  • The difference between the default Login Redirect API and the regular web client APIs is that, the Login Redirect API is only meant for the default login redirect page of the application where the users are redirected to, after they login. However, you can append routes to a web client's target URL and create APIs for different routes for regular web client APIs.
  • If you have not hosted a web client in your Catalyst project, this API will not be created.

Auto-Created APIs

You can enable Catalyst to automatically create APIs for the functions that you choose, or for the web client, using the auto-create method. Auto creating APIs is only available until you create your first API in API Gateway.

Auto-create can be used when you have a large number of functions configured in your Catalyst project, and creating individual APIs for each of them would be very time consuming.

When you use auto-create to create APIs, these protocols are followed:

  • If you have configured definitions for your functions in Security Rules, they will be migrated to API Gateway automatically during auto-create. If you have not configured any definitions, the default rules will be applied.
  • The APIs created for a function during auto-create will contain the HTTP methods and authentication configured for it in the Security Rules.
  • Request methods and URL:
    • If all five HTTP methods (GET, PUT, POST, DELETE, PATCH) are enabled for a function in Security Rules, a single API will automatically be created with the request method 'ANY' for the function.
    • If one or more of the five HTTP methods is disabled for a function in Security Rules, individual APIs will be created for each of the other methods.
    • The request URL of a function will be the same as its default target URL or the function URL in auto-create, since the request URL and target URL are the same in Security Rules.
    • If there is a regex pattern in the request URL of a function, the same pattern will be assigned to the target URL.
  • Authentication:
    • If the authentication method for a function in Security Rules is optional, the request processor will automatically be set to No Authentication for the function's APIs during auto-create.
    • If authentication for a function in Security Rules is enabled, Catalyst Users Authentication and OAuth-based Authentication will be automatically enabled for the function's APIs in API Gateway.
  • Throttling: The values for general throttling and IP-based throttling for a function's APIs will be set to Not configured by default during auto-create.
  • API name: An API created using auto-create for a function will be named in the format: FunctionName_HTTPMethod. An API created for a web client using auto-create will be named in the format: WebclientName.
  • Web client API: The values for general throttling and IP-based throttling for a web client will be set to Not configured. As mentioned, earlier authentication is not available for web client APIs. The request URL of a web client will also be the same as its target web app URL.
  • Hard limits: The hard limit for the number of APIs that can be created is 1000 APIs/project.

After the APIs are created for your functions and web client using auto-create, you can edit individual APIs and modify the default values as required.

Custom API

You can create a custom API for your function or web client at any time and configure the parameters of the API. You can define the request method and URL, the target, authentication methods, throttling, and more based on your requirements. Creating a custom API does not migrate the configurations of a function from Security Rules.

 

Architecture

Catalyst API Gateway's architecture is shown below:

Catalyst API Gateway performs tasks in the following sequence:

  1. Reading the request method and URL of the client request
  2. Searching for an API that you have configured for the particular request method and URL
  3. Initiating the API, if available, or denying the request if the API is unavailable
  4. Checking the throttling configuration and verifying if the request is within the defined rate limits, if applicable
  5. Checking the authentication configuration and initiating a handler to verify the credentials, if applicable
  6. Enabling the API to redirect the client to the configured target URL, if all validations are passed
 

Benefits

  1. Efficient API Management

    Catalyst API Gateway enables you to manage all your APIs in a single place. It provides a single endpoint for all your clients, and allows you to create custom APIs with flexible definitions for each request. The ability to aggregate all HTTP supported request methods into one method (ANY) increases efficiency and reduces manual efforts in creating and maintaining a large number of APIs. It also minimizes the number of round trips between the client and the application server, improving the end user experience. 
  2. Enhanced Security for the Application's Backend

    Catalyst API Gateway acts as an intermediate layer between the client and the server, and prevents direct communication between them. This insulates the application from the clients, and prevents public exposure of its backend architecture and endpoints. API Gateway decreases the risk of potential threats associated with vulnerable exposure by completely decoupling the clients from services. The authentication methods also act as additional security boosters, and ensure protection of the application and user data. 
  3. Offloading Functionalities from Individual Services

    API Gateway offloads functionalities such as authentication and throttling from individual microservices, and handles everything in a consolidated manner. This lessens the responsibilities of individual services, as they do not need to be designed to manage authentication or throttling by themselves. API Gateway acts as a cohesive unit to manage all your APIs centrally and streamlines your application's functionality.
  4. High Performance at any Scale

    Throttling the rate limits of an API improves the application's performance and provides a rich user experience. It helps the backend systems withstand traffic spikes and prevents excessive use of resources. Throttling also ensures that a particular set of clients alone do not suffocate the backend resources, and distributes the application's efficiency evenly between all clients. You can design usage plans in your application based on the throttling limits that you configure. Catalyst API Gateway ensures that your application is fast, robust, reliable, and consistent.
 

Implementation

The implementation section is a step-by-step procedure guide to configure API Gateway from the Catalyst web console. You can learn about working with API Gateway from the CLI from the CLI help documentation.

Enable API Gateway

You must enable API Gateway for your project before you access it for the first time. As discussed earlier, when you enable the API Gateway for your Catalyst application, the configurations in Security Rules are automatically disabled. The functions and the web client hosted in your Catalyst project will immediately become inaccessible until you create APIs for them. You should therefore proceed with caution.

Ensure that you create APIs for all your functions and web client immediately after enabling API Gateway. You must also ensure that the end users do not access them in the meantime. You can learn about disabling API Gateway from this section.

To enable API Gateway for your Catalyst application from the console:

  1. Navigate to Add-on Services under Discover and click Get Started on the API Gateway window.
  2. Click Enable Now in the API Gateway feature page.
  3. Click Proceed in the confirmation window.

You will receive a notification in the console once API Gateway is enabled for your Catalyst project.

 

Create an API

Before you begin, you must ensure that you have hosted at least one function or the web client in your Catalyst project, to create an API for it.

Note: You can create upto 1000 APIs in a project in the development environment. There are no upper limits for rule creation in the production environment.

Auto-Create

You can only use auto-create to create APIs automatically when you enable API Gateway for your project for the first time. If you have already created a custom API, you will not be able to access auto-create.

Refer to this section for protocols to be followed when migrating definitions from Security Rules.

To create APIs for your functions or the web client using auto-create:

  1. Click Create API after you enable API Gateway in the Catalyst console.
  2. Select Auto-create API and click Next.
  3. All your Basic I/O and Advanced I/O functions, and the web client are selected by default.

    Unselect the services that you don't want to create APIs for and click Create.

    Catalyst will initiate the API creation process.

Once the APIs are created, you will receive a notification in your console. The APIs will be listed in the API Gateway page.

You can edit the default values set for these APIs, and individually configure them based on your requirements.

As discussed in this section, the default Login Redirect API is also created for the web client hosted in the project.


 

Create a Custom API

You can create a custom API either immediately after enabling API Gateway or at any time after using auto-create.

To create a custom API for your functions or the web client:

  1. Click Create API from the API Gateway page.

    You can also create it by selecting Create a custom API in the pop-up box after enabling API Gateway and clicking Next.

    This will open the Create API window.
  2. Enter a unique name for the API. Select a request method and enter the request URL.
    Notes:
    • You can only select the GET method for a web client.
    • The combination of the request URL and the request method should be unique. You will not be able to create more than one API for a specific combination of request URL and request method.
    Select the target component and then select the specific function or web client.

    If you selected an Advanced I/O function or a web client, you can append a route to the default target URL. A preview of the request URL will also be displayed.

    Select the authentication methods if you require authentication. You can select any or all of these methods, and implement any one of them while providing the request URL.

    Configure the throttling limits for the API. You can configure either or both of the throttling methods.
  3. Click Create.

The API will be created and listed in the API Gateway page.


 

Edit an API

You can edit an auto-created or a custom API at any time and modify its definitions in the following way:

  1. Click Edit for the API.
  2. Modify the required values and click Update.
 

Delete an API

You can delete an API in the following way:

  1. Click Delete for the API.
  2. Click Yes, Proceed in the confirmation box.
Note: Deleting an API will render its associated target URL inaccessible.
 

Disable API Gateway

You can disable API Gateway at any time and switch to the definitions configured in the Security Rules. If you re-enable API Gateway after disabling it, all the APIs that you had created will still be available and will immediately be re-enabled when API Gateway is re-enabled. You will not have to create the same APIs again.

To disable API Gateway:

  1. Click the ellipsis icon on the API Gateway page and click Disable.
  2. Type "DISABLE" in the text box and click Confirm.

The API Gateway will now be disabled and Security Rules will immediately be automatically enabled.

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: support@zohocatalyst.com