Instructional Guide for API Configuration¶

This guide will walk you through configuring the conf/api.yaml file, including settings for DNS, Lambda function, and personalized ranking. The guide is divided into three sections: Getting Started, Parameter Definitions, and Examples.

Getting Started¶

Follow these steps to configure the settings for your YAML file:

Step 1: Configure CloudWatch Role Settings¶

To specify the IAM role that Amazon API Gateway uses to write API logs to Amazon CloudWatch Logs, follow these instructions:

If you already have a CloudWatch role, replace your-cloud-watch-role-name with your actual CloudWatch role name:

cloud_watch_role_name: your-cloud-watch-role-name  # Uncomment and replace 'your-cloud-watch-role-name' with your actual CloudWatch role name, if you already have one.

If you don't have a CloudWatch role, comment out the cloud_watch_role_name line. We will create a default CloudWatch role and use it:

# cloud_watch_role_name: your-cloud-watch-role-name  # Uncomment and replace 'your-cloud-watch-role-name' with your actual CloudWatch role name, if you already have one.

Step 2: Configure Domain Name System Settings¶

You can set a custom domain name for your API, which consists of domain_name and sub_domain_name, formatted as {sub_domain_name}.{domain_name}. For example, if the domain_name is example.com and the sub_domain_name is abc, the custom domain name will be abc.example.com.

Replace your-domain-name and your-sub-domain-name with your actual domain name and sub-domain name. Replace your-certificate-arn with your SSL/TLS certificate ARN.

domain_name_system:
  domain_name: your-domain-name  # Replace 'your-domain-name' with your actual domain name (e.g., example.com)
  sub_domain_name: your-sub-domain-name  # Replace 'your-sub-domain-name' with your actual subdomain name (e.g., www)
  certificate_arn: your-certificate-arn  # Replace 'your-certificate-arn' with the ARN of your SSL/TLS certificate (e.g., arn:aws:acm:region:account-id:certificate/certificate-id)

If you don't want to set a custom domain name for your API, comment out the domain_name_system section:

# domain_name_system:
#   domain_name: your-domain-name  # Replace 'your-domain-name' with your actual domain name (e.g., example.com)
#   sub_domain_name: your-sub-domain-name  # Replace 'your-sub-domain-name' with your actual subdomain name (e.g., www)
#   certificate_arn: your-certificate-arn  # Replace 'your-certificate-arn' with the ARN of your SSL/TLS certificate (e.g., arn:aws:acm:region:account-id:certificate/certificate-id)certificate.

Step 3: Configure Provisioned Concurrency Settings¶

You can configure provisioned concurrency for two functions. The api_router Lambda function handles API requests, while the log_handler Lambda function saves logs.

Adjust the minimum and maximum capacity, as well as the utilization target, based on your needs for the api_router and log_handler Lambda functions.

provisioned_concurrency:
  ##  The api router Lambda function is responsible for handling API requests.
  ##  By default, this setting is disabled. To enable it, uncomment the 'api_router' section.
  api_router:
    min_capacity: 1  # Minimum number of instances to keep running (adjust based on your needs)
    max_capacity: 3  # Maximum number of instances allowed (adjust based on your needs)
    utilization_target: 0.8  ##  Target utilization percentage (adjust based on your needs, e.g., 0.8 for 80%)

  ##  The log handler Lambda function is responsible for saving logs.
  ##  By default, this setting is disabled. To enable it, uncomment the 'log_handler' section.
  log_handler:
    min_capacity: 1  # Minimum number of instances to keep running (adjust based on your needs)
    max_capacity: 3  # Maximum number of instances allowed (adjust based on your needs)
    utilization_target: 0.8  # Target utilization percentage (adjust based on your needs, e.g., 0.8 for 80%)

If you don't want to set provisioned concurrency for your Lambda functions, comment out the api_router and log_handler sections:

provisioned_concurrency:
  ##  The api router Lambda function is responsible for handling API requests.
  ##  By default, this setting is disabled. To enable it, uncomment the 'api_router' section.
  # api_router:
  #   min_capacity: 1  # Minimum number of instances to keep running (adjust based on your needs)
  #   max_capacity: 3  # Maximum number of instances allowed (adjust based on your needs)
  #   utilization_target: 0.8  ##  Target utilization percentage (adjust based on your needs, e.g., 0.8 for 80%)

  ##  The log handler Lambda function is responsible for saving logs.
  ##  By default, this setting is disabled. To enable it, uncomment the 'log_handler' section.
  # log_handler:
  #   min_capacity: 1  # Minimum number of instances to keep running (adjust based on your needs)
  #   max_capacity: 3  # Maximum number of instances allowed (adjust based on your needs)
  #   utilization_target: 0.8  # Target utilization percentage (adjust based on your needs, e.g., 0.8 for 80%)

Step 4: Configure Personalized Search Settings¶

If you already have a campaign for ranking, you can use it to personalize your search results.

Replace your-campaign-arn with your actual campaign ARN from the Personalized-Ranking recipe in Amazon Personalize.

personalized_ranking:
  campaign_arn: your-campaign-arn  # Replace 'your-campaign-arn' with your actual campaign ARN from AWS Personalize

If you set the campaign_arn, it will be used to generate personalized rankings of search results for a specific user.

Note

You need to train the campaign yourself in advance; we do not train the campaign for you.

If you don't want to personalize your search results, comment out the personalized_ranking section:

# personalized_ranking:
#   campaign_arn: your-campaign-arn  # Replace 'your-campaign-arn' with your actual campaign ARN from AWS Personalize

Step 5: Save Configuration¶

Save your YAML file after filling in the necessary information.

Parameter Definitions¶

This section provides a detailed explanation of each parameter in the YAML file.

Parameter	Data Type	Required	Description
`cloud_watch_role_name`	String	Optional	The role name used by Amazon API Gateway to write API logs to Amazon CloudWatch Logs.
`domain_name_system.domain_name`	String	Optional	The primary domain name for your API.
`domain_name_system.sub_domain_name`	String	Optional	The sub-domain name for your API.
`domain_name_system.certificate_arn`	String	Optional	ARN of your SSL/TLS certificate.
`provisioned_concurrency.api_router.min_capacity`	Int	Optional	The minimum number of instances to keep running for the `api_router` Lambda function.
`provisioned_concurrency.api_router.max_capacity`	Int	Optional	The maximum number of instances allowed for the `api_router` Lambda function.
`provisioned_concurrency.api_router.utilization_target`	Float	Optional	The target utilization percentage for the `api_router` Lambda function.
`provisioned_concurrency.log_handler.min_capacity`	Int	Optional	The minimum number of instances to keep running for the `log_handler` Lambda function.
`provisioned_concurrency.log_handler.max_capacity`	Int	Optional	The maximum number of instances allowed for the `log_handler` Lambda function.
`provisioned_concurrency.log_handler.utilization_target`	Float	Optional	The target utilization percentage for the `log_handler` Lambda function.
`personalized_ranking.campaign_arn`	String	Optional	The Amazon Resource Name (ARN) of your AWS Personalize campaign.

Examples¶

Here are some examples to help you understand how to configure the YAML file. If you do not want to use some configures, simply use # to comment out the sections.

Example 1: Configuring for a Bookstore Application¶

##  You can specify the IAM role that Amazon API Gateway uses to write API logs to Amazon CloudWatch Logs.
cloud_watch_role_name: api-cloud-watch-ap-northeast-1


##  You can name custom domain name for your API.
domain_name_system:
  domain_name: bookstore.com
  sub_domain_name: www
  certificate_arn: arn:aws:acm:us-west-2:123456789012:certificate/abcdef12-3456-7890-abcd-ef1234567890


##  You can set up provisioned concurrency for Lambda functions.
provisioned_concurrency:
  ##  The api router Lambda function is responsible for handling API requests.
  api_router:
    min_capacity: 2
    max_capacity: 5
    utilization_target: 0.75

  ##  The log handler Lambda function is responsible for saving logs.
  log_handler:
    min_capacity: 1
    max_capacity: 3
    utilization_target: 0.8


##  You can enable personalized search.
personalized_ranking:
  campaign_arn: arn:aws:personalize:us-west-2:123456789012:campaign/book-recommendation-campaign

Example 2: Configuring for a Movie Streaming Service¶

##  You can specify the IAM role that Amazon API Gateway uses to write API logs to Amazon CloudWatch Logs.
cloud_watch_role_name: api-cloud-watch-ap-northeast-1


##  You can name custom domain name for your API.
domain_name_system:
  domain_name: moviestreaming.com
  sub_domain_name: app
  certificate_arn: arn:aws:acm:us-east-1:123456789012:certificate/abcdef12-3456-7890-abcd-ef1234567890


##  You can set up provisioned concurrency for Lambda functions.
provisioned_concurrency:
  ##  The api router Lambda function is responsible for handling API requests.
  api_router:
    min_capacity: 3
    max_capacity: 10
    utilization_target: 0.85

  ##  The log handler Lambda function is responsible for saving logs.
  log_handler:
    min_capacity: 2
    max_capacity: 6
    utilization_target: 0.9


##  You can enable personalized search.
personalized_ranking:
  campaign_arn: arn:aws:personalize:us-east-1:987654321098:campaign/movie-recommendation-campaign

Example 3: Configuring for Not Using Provisioned Concurrency on `api_router`¶

##  You can specify the IAM role that Amazon API Gateway uses to write API logs to Amazon CloudWatch Logs.
cloud_watch_role_name: api-cloud-watch-ap-northeast-1


##  You can name custom domain name for your API.
domain_name_system:
  domain_name: moviestreaming.com
  sub_domain_name: app
  certificate_arn: arn:aws:acm:us-east-1:123456789012:certificate/abcdef12-3456-7890-abcd-ef1234567890


##  You can set up provisioned concurrency for Lambda functions.
provisioned_concurrency:
  ##  The api router Lambda function is responsible for handling API requests.
  # api_router:
  #   min_capacity: 3
  #   max_capacity: 10
  #   utilization_target: 0.85

  ##  The log handler Lambda function is responsible for saving logs.
  log_handler:
    min_capacity: 2
    max_capacity: 6
    utilization_target: 0.9


##  You can enable personalized search.
personalized_ranking:
  campaign_arn: arn:aws:personalize:us-east-1:987654321098:campaign/movie-recommendation-campaign