Skip to main content

Setup Procedure

Smart API Gateway Usage Procedure​

Below is the procedure for configuring the SaaSus Platform Smart API Gateway feature to easily publish and manage your APIs.

Step 1: Preliminary Steps (Setup of SaaS Environment and App)​

  • Create a SaaSus Platform Account
    You need a SaaSus Platform account to use this feature.
    Access SaaSus Platform, create a SaaSus Platform account, and log in.

  • Prepare the AWS Environment for Testing
    You need an AWS account to use this feature.
    If you do not have one, access Create an AWS Account to sign up for AWS.

  • SaaS Environment and Sample App
    Use CloudFormation to create a SaaS environment and sample app in AWS.
    In the AWS environment you will use for verification, run the CloudFormation below.
    After execution, access the URL listed in the CloudFormation outputs, enter the password, and log in to the VSCode environment.
    Create a SaaS Environment and Sample App

  • SDK Setup
    The SDK setup is performed using the following steps:

  1. Build a package with the SaaSus Java SDK and install it in your local repository.

    cd saasus-sdk-java
    mvn clean package
    mvn install:install-file -Dfile=target/saasus-sdk-java-1.0.0.jar -DgroupId=io.saasus -DartifactId=saasus-java -Dversion=0.0.1 -Dpackaging=jar
    Since the steps have already been configured, just verify what is being done

  2. In the implementation-sample-smart-api-gateway/pom.xml file, add the following under the dependencies tag and the profiles tag.

    <!-- saasus platform sdk -->
    <dependency>
      <groupId>io.saasus</groupId>
      <artifactId>saasus-java</artifactId>
      <version>0.0.1</version>
    </dependency>
    <!-- saasus platform sdk -->

    <!-- smart api gateway parameter setting -->
    <profiles>
      <profile>
        <id>with-parameters</id>
        <build>
          <plugins>
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-compiler-plugin</artifactId>
              <version>3.8.1</version>
              <configuration>
                <compilerArgs>
                  <arg>-parameters</arg>
                </compilerArgs>
              </configuration>
            </plugin>
          </plugins>
        </build>
      </profile>
    </profiles>
    <!-- smart api gateway parameter setting -->

  3. Make the necessary configurations in the implementation-sample-smart-api-gateway project.

    cd implementation-sample-smart-api-gateway
    mvn clean package

    cp .env.example .env
    vi .env

    SAASUS_SAAS_ID="xxxxxxxxxx"
    SAASUS_API_KEY="xxxxxxxxxx"
    SAASUS_SECRET_KEY="xxxxxxxxxx"

    docker compose up -d
    info

    For details on how to obtain SAASUS_SAAS_ID, SAASUS_API_KEY, and SAASUS_SECRET_KEY, please see:
    Reconfirming SaaS ID, API Key, and Client Secret

Since the steps have already been configured, just verify what is being done

Step 2: Annotation Settings in Source Code​

  1. Add annotations to the methods you want to publish so that they can be used as API endpoints.

    As an example this time,
    src/main/java/implementsample/service/InventoryService.java
    we will call the getInventoryEntryPoint method via the API.

    Smart API Gateway is designed to call static methods.
    Therefore, we create a static method that will be called from Smart API Gateway, inside which we call TenantInventory.
    Then, we add the @SaaSusAPI annotation to the newly created static method to declare its use as an endpoint of the Smart API Gateway.

package implementsample.service;

import java.util.List;

import implementsample.repository.InventoryRepository;
import implementsample.util.TenantApiClient;
import saasus.sdk.modules.SaaSusAPI;
import implementsample.dto.InventoryDto;

public class InventoryService {
    public List<InventoryDto> getInventory(String tenantId) {
        // Retrieve inventory information for the corresponding tenant ID
        return InventoryRepository.TenantInventory.getOrDefault(tenantId,
                InventoryRepository.TenantInventory.get("default"));
    }

    @SaaSusAPI(path = "getInventory")
    public static List<InventoryDto> getInventoryEntryPoint(String xApiKey) {
        // Retrieve the tenant ID from the API key
        TenantApiClient tenantClient = new TenantApiClient();
        String tenantId = tenantClient.getTenantIdFromApiKey(xApiKey);

        return InventoryRepository.TenantInventory.getOrDefault(tenantId,
                InventoryRepository.TenantInventory.get("default"));
    }
}

Step 3: API Server Startup Settings​

  1. We added the src/main/java/implementsample/ApiServerListener.java class so that the saasus-sdk API server starts when the application starts.
// saasus api server
import saasus.sdk.util.apiserver.ApiServer;

...omitted...

// Start the API server on port 8083
ApiServer.start(8083);
  1. The following settings are required for Application Load Balancer (already configured in CloudFormation):
    • Listener: Port 8083
    • Target Group: Create a target group for port 8083
    • Security Group: Allow access on port 8083 between the ALB and the application

Step 4: Integrate and Compress Source Code​

Because the source code will be uploaded in Step 5, collect and compress it into a ZIP file using the shell script below.

bash java_files_collector.sh <path to your application>

Example:

cd /Workshop/implementation-sample-smart-api-gateway
bash java_files_collector.sh src/main/java/implementsample

A java_files_archive.zip file is created.
Please download this file.

This completes the configuration within the SaaS application.

Step 5: Upload the ZIP File​

  1. Access the Smart API Gateway feature screen in the SaaSus Platform Developer Console.

  2. Upload the generated ZIP file from the screen.

Step 6: Permission & Infrastructure Settings​

  1. Go to the Permission tab and create CloudFormation for Assume Role.
  2. Register the Role ARN and External ID you created.
  3. Register the VPC ID and Subnet IDs of the VPC in which you will create PrivateLink (Network Load Balancer).
  4. Register the ALB ARN of your Application Load Balancer.
    info

    Make sure you enter multiple Subnet IDs for the Subnet IDs.

When the setup is complete, the infrastructure connecting the SaaSus Platform and your environment will be created.

Step 7: Publish and Access the API​

  1. Publish the API
  2. You can access it via the domain for the API endpoint.

How to Access the API​

  • API Key is required to access the API. Generate an API Key in the Tenant Management Screen of the SaaSus Platform Operation Console and use it for access.
  • Check the API methods in Throttling&Role under the method path.
  • Access the domain of the API endpoint as follows:

Access Example​

$ curl -v -X GET https://<domain>/<api method path> -H 'x-api-key:<YourIssuedAPIKey>'

Example​

$ curl -v -X GET https://xxxxxxxxxxxxxxxxxxxxx/inventory-controller/get-inventory?apiKey=d296b330-3cce-40b6-88c3-035a1d86981f -H 'x-api-key:azydsktcf1b93Mmjxuex7CEbEoV7OjrGk0RIqgzCQtc'

Step 8: Throttling Settings​

  • From Throttling&Role, select the target method path and configure the throttling settings.
  • For testing, set a limit of 2 requests per 1 minute.
  • When the settings are complete, the API access restriction is applied.
  • Make multiple accesses to verify that throttling works.
info
  • Throttling settings can be applied by setting the number of requests within a specified range (seconds).
    • Tenant-based throttling
      • The limit is applied to the total number of API calls made with both the tenant's API key and the user's API key.
    • User-based throttling
      • With the tenant's API key, API calls can be made without limit.
      • When using a user's API key, the number of API calls per user is restricted.

Step 9: Authorization (Role) Settings​

  • For testing, create a role called "general user" in the Role Definitions of the SaaSus Platform Developer Console.
  • Role-based authorization requires a user's API Key. Create a user in the User Management Screen of the SaaSus Platform Operation Console and issue an API Key.
  • From Role Management in the SaaSus Platform Operation Console, assign the created "general user" role to the user.
  • From Throttling&Role, select the target method path and configure the SaaS administrator role.
  • Once the settings are complete, API access restrictions based on roles are applied.
  • Use the user's API key to check the operation of role-based authorization.
info
  • Role-based authorization is controlled by the user's role, so it only applies to the user's API Key.
  • To issue a user's API key, the user must belong to a tenant.
  • The tenant's API Key can be used to access the API regardless of the assigned role.

Step 10: Domain Settings​

  • Configure the domain from Custom Domain.
  • Add the displayed CNAME record to your own DNS server.
  • After domain configuration is complete, the domain for the API endpoint is updated.
  • You can then access the API via the newly configured domain.

Step 11: IP Restriction Settings​

  • Set IP restrictions in the Tenant Management Screen of the SaaSus Platform Operation Console.
  • After configuring IP restrictions, the API can only be accessed from the specified IP addresses.

Deleting the Test Environment​

  • Log back in to the VSCode environment and run the following commands:
  • Retrieve the vpc endpoint service id created from the t-<tenantid>-saasus-setup-private-link-on-saas CloudFormation resource
  • Configure aws cli (for example, using aws configure) to set your access key and secret key
  • Execute reject_vpc_endpoints.sh <vpc endpoint service id> to reject the endpoint connection for that vpc endpoint service id (failing to do so will result in an error when deleting CloudFormation)
  • Delete the CloudFormation stack t-<tenantid>-saasus-setup-private-link-on-saas
  • Delete the CloudFormation stack for the SaaS sample