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:

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.

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/CusomerPortal/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.

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.

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:
  

    

        
copy
        

            

        
    
    

         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:
  

    

        
copy
        

            

        
    
    

         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:

    

        
copy
        

            

        
    
    

         curl -X POST \
https://shipmenttracking-61317105.catalystserverless.com/CustomerPortal/create \
-H "Authorization: Zoho-oauthtoken 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.