Yandex Cloud
  • Services
  • Solutions
  • Why Yandex Cloud
  • Pricing
  • Documentation
  • Contact us
Get started
Language / Region
© 2022 Yandex.Cloud LLC
Yandex API Gateway
  • Getting started
  • Step-by-step instructions
    • All instructions
    • Creating API gateways
    • Updating API gateways and their specifications
    • Connecting a domain
    • Deleting API gateways
    • Monitoring
    • Viewing the execution log
  • Practical guidelines
    • Deploying a web application
    • Developing a skill for Alice and a website with authorization
    • Developing a Slack bot
    • Developing a Telegram bot
  • Concepts
    • Relationship between service resources
    • Specification extensions
      • Overview
      • Static response
      • Invoking a function
      • Integration with Serverless Containers
      • Access via HTTP
      • Integration with Object Storage
      • DataSphere integration
      • Data Streams integration
      • Message Queue integration
      • Greedy parameters
      • Generalized HTTP method
      • Authorization using a function
    • Quotas and limits
  • Access management
  • Pricing policy
  • API reference
    • Authentication in the API
    • gRPC
      • Overview
      • ApiGatewayService
      • OperationService
    • REST
      • Overview
      • ApiGateway
        • Overview
        • addDomain
        • create
        • delete
        • get
        • getOpenapiSpec
        • list
        • listAccessBindings
        • listOperations
        • removeDomain
        • setAccessBindings
        • update
        • updateAccessBindings
  • Questions and answers
  1. Getting started

Getting started with API Gateway

Written by
Yandex Cloud
  • Before you begin
  • Create an API gateway
  • Access the API gateway
  • Add an integration with the function
    • Create a function
    • Extend the API gateway specification
    • Access the function via the API gateway

Using these instructions, you'll create and test different types of extensions: first, you'll set up an API gateway for getting static responses and then add integration for invoking functions.

Before you begin

To get started in Yandex Cloud:

  1. Log in to the management console. If you aren't registered, go to the management console and follow the instructions.
    1. On the billing page, make sure you linked a billing account and it has the ACTIVE or TRIAL_ACTIVE status. If you don't have a billing account, create one.
  2. If you don't have a folder, create one.

Create an API gateway

Management console
Terraform
  1. In the management console, select the folder where you wish to create an API gateway.

  2. In the list of services, select API Gateway.

  3. Click Create API gateway.

  4. In the Name field, enter numbers.

  5. (optional) In the Description field, enter a description.

  6. In the Specification section, add a specification:

    openapi: "3.0.0"
    info:
      version: 1.0.0
      title: Test API
    paths:
      /hello:
        get:
          summary: Say hello
          operationId: hello
          parameters:
            - name: user
              in: query
              description: User name to appear in greetings
              required: false
              schema:
                type: string
                default: 'world'
          responses:
            '200':
              description: Greeting
              content:
                'text/plain':
                   schema:
                     type: "string"
          x-yc-apigateway-integration:
            type: dummy
            http_code: 200
            http_headers:
              'Content-Type': "text/plain"
            content:
              'text/plain': "Hello, {user}!\n"
    
  7. Click Create.

With Terraform, you can quickly create a cloud infrastructure in Yandex Cloud and manage it by configuration files. They store the infrastructure description in HashiCorp Configuration Language (HCL). Terraform and its providers are distributed under the Mozilla Public License.

For more information about the provider resources, see the documentation on the Terraform site or mirror site.

If you change the configuration files, Terraform automatically determines which part of your configuration is already deployed and what should be added or removed.

If you don't have Terraform, install it and configure the Yandex Cloud provider.

To create an API gateway:

  1. Describe the parameters of the yandex_api_gateway resource in the configuration file:

    • name: API gateway name. Name format:

      • The length can be from 3 to 63 characters.
      • It may contain lowercase Latin letters, numbers, and hyphens.
      • The first character must be a letter. The last character can't be a hyphen.
    • description: API gateway description.

    • labels: Labels for the API gateway. Set a key-value pair.

    • spec: API gateway specification.

    Example configuration file structure:

    resource "yandex_api_gateway" "test-api-gateway" {
      name        = "<API gateway name>"
      description = "<API gateway description>"
      labels      = {
        label       = "label"
        empty-label = ""
      }
      spec = <<-EOT
        openapi: "3.0.0"
        info:
          version: 1.0.0
          title: Test API
        paths:
          /hello:
            get:
              summary: Say hello
              operationId: hello
              parameters:
                - name: user
                  in: query
                  description: User name to appear in greetings
                  required: false
                  schema:
                    type: string
                    default: 'world'
              responses:
                '200':
                  description: Greeting
                  content:
                    'text/plain':
                      schema:
                        type: "string"
              x-yc-apigateway-integration:
                type: dummy
                http_code: 200
                http_headers:
                  'Content-Type': "text/plain"
                content:
                  'text/plain': "Hello, {user}!\n"
      EOT
    }
    

    For more information about the resource parameters in Terraform, see the provider documentation.

  2. Make sure that the configuration files are correct.

    1. In the command line, go to the directory where you created the configuration file.

    2. Run the check using the command:

      terraform plan
      

    If the configuration is described correctly, the terminal displays a list of created resources and their parameters. If there are errors in the configuration, Terraform points them out.

  3. Deploy the cloud resources.

    1. If the configuration doesn't contain any errors, run the command:

      terraform apply
      
    2. Confirm the resource creation: type yes in the terminal and press Enter.

      Afterwards, all the necessary resources are created in the specified folder. You can verify that the resources are there and properly configured in the management console or using the following CLI command:

      yc serverless api-gateway get <API gateway name>
      

Access the API gateway

  1. In the management console, select the folder containing the API gateway.

  2. In the list of services, select API Gateway and click the name of the created API gateway.

  3. Copy the Domain field value and create a link in the format: https://<domain>/hello?user=API. The resulting link should look like this:

    https://falrnjna8r5vj88ero6a.apigw.yandexcloud.net/hello?user=API
    
  4. Access the API gateway using curl with one of the commands:

    curl https://falrnjna8r5vj88ero6a.apigw.yandexcloud.net/hello?user=API
    curl https://falrnjna8r5vj88ero6a.apigw.yandexcloud.net/hello
    

    Result:

    Hello, API!
    Hello, world!
    

Add an integration with the function

Create a function

Create a function to get a list of numbers. Read more about functions in the Cloud Functions documentation.

Management console
Terraform

To create a function:

  1. Create a function:
    1. In the management console, select the folder to create your function in.
    2. Click Create resource.
    3. Select Function.
    4. In the Name field, specify list.
    5. Click Create.
    6. Make your function public.
  2. Create the function version:
    1. In the window that opens, select the function you created.

    2. Under Latest version, click Create in editor.

    3. In the window that opens, in the Runtime environment field, select nodejs12.

    4. In the Method field, select the code editor.

    5. Click Create file in the editor below.

      1. In the window that opens, enter the index.js file name.
      2. Click Create.
    6. Paste the following code in the index.js file:

      module.exports.handler = async (event) => {
          return {
              "statusCode": 200,
              "headers": {"content-type": "application/json"},
              "body": "[0, 1, 2]"
          };
      };
      
    7. In the Entry point field, enter index.handler.

    8. Click Create version.

To create a function:

  1. Prepare a ZIP archive with the function code:

    1. Save the following code to a file named index.js:

      module.exports.handler = async (event) => {
          return {
              "statusCode": 200,
              "headers": {"content-type": "application/json"},
              "body": "[0, 1, 2]"
          };
      };
      
    2. Add index.js to the hello-js.zip archive.

  2. Describe the yandex_function resource parameters in the configuration file:

    resource "yandex_function" "test-function" {
      name               = "test-function"
      description        = "Test function"
      user_hash          = "first-function"
      runtime            = "nodejs12"
      entrypoint         = "index.handler"
      memory             = "128"
      execution_timeout  = "10"
      service_account_id = "<Service account ID>"
      tags               = ["my_tag"]
      content {
        zip_filename = "<path to ZIP archive>"
      }
    }
    

    Where:

    • name: Function name.
    • description: Text description of the function.
    • user_hash: An arbitrary string that identifies the function version. When the function changes, update this string, too. The function will update when this string is updated.
    • runtime: The function runtime environment.
    • entrypoint: Function name in the source code that will serve as an entry point to the applications.
    • memory: The amount of memory allocated for function execution, in MB.
    • execution_timeout: Function execution timeout.
    • service_account_id: ID of the service account that should be used to invoke the function.
    • tags: Function tags.
    • content: Function source code.
    • content.0.zip_filename: Path to the ZIP archive containing the function source code.

    For more information about the yandex_function resource parameters, see the provider documentation.

  3. Make sure that the configuration files are correct.

    1. In the command line, go to the directory where you created the configuration file.

    2. Run the check using the command:

      terraform plan
      

    If the configuration is described correctly, the terminal displays a list of created resources and their parameters. If there are errors in the configuration, Terraform points them out.

  4. Deploy the cloud resources.

    1. If the configuration doesn't contain any errors, run the command:

      terraform apply
      
    2. Confirm the resource creation: type yes in the terminal and press Enter.

      Afterwards, all the necessary resources are created in the specified folder. You can verify that the resources are there and properly configured in the management console or using the following CLI command:

      yc serverless function list
      

Extend the API gateway specification

Add function information to the API gateway specification.

Management console
Terraform

To update an API gateway specification:

  1. In the management console, select the folder where you want to update an API gateway.

  2. In the window that opens, select the API gateway and click .

  3. In the menu that opens, click Edit.

  4. Under Specification, add an extended version of the specification

    The /numbers method, which uses the cloud_functions type x-yc-apigateway-integration extension, invokes a function by ID.

    To ensure that the API gateway works properly, in the function_id parameter, specify the ID of the function to invoke.
    To let the API gateway access a private function, in the service_account_id parameter, specify a service account that has the rights to invoke the function.

    openapi: "3.0.0"
    info:
      version: 1.0.0
      title: Test API
    paths:
      /hello:
        get:
          summary: Say hello
          operationId: hello
          parameters:
            - name: user
              in: query
              description: User name to appear in greetings
              required: false
              schema:
                type: string
                default: 'world'
          responses:
            '200':
              description: Greeting
              content:
                'text/plain':
                   schema:
                     type: "string"
          x-yc-apigateway-integration:
            type: dummy
            http_code: 200
            http_headers:
              'Content-Type': "text/plain"
            content:
              'text/plain': "Hello, {user}!\n"
      /numbers:
        get:
          summary: List some numbers
          operationId: listNumbers
          responses:
            '200':
              description: Another example
              content:
                'application/json':
                   schema:
                     type: "array"
                     items:
                       type: "integer"
          x-yc-apigateway-integration:
            type: cloud_functions
            function_id: <function ID >
            service_account_id: <service account ID>
    

To add function information to the API gateway specification:

  1. Open the Terraform configuration file and add the /numbers method that uses the cloud_functions type x-yc-apigateway-integration extension to invoke a function by ID. Under spec, change the API gateway specification by specifying the following parameters:

    • function_id: Function ID.
    • service_account_id: ID of the service account with rights to invoke a function.

    Extended API gateway specification:

    ...
    
      spec = <<-EOT
        openapi: "3.0.0"
        info:
          version: 1.0.0
          title: Test API
        paths:
          /hello:
            get:
              summary: Say hello
              operationId: hello
              parameters:
                - name: user
                  in: query
                  description: User name to appear in greetings
                  required: false
                  schema:
                    type: string
                    default: 'world'
              responses:
                '200':
                  description: Greeting
                  content:
                    'text/plain':
                      schema:
                        type: "string"
              x-yc-apigateway-integration:
                type: dummy
                http_code: 200
                http_headers:
                  'Content-Type': "text/plain"
                content:
                  'text/plain': "Hello again, {user}!\n"
          /numbers:
            get:
              summary: List some numbers
              operationId: listNumbers
              responses:
                '200':
                  description: Another example
                  content:
                    'application/json':
                      schema:
                        type: "array"
                        items:
                          type: "integer"
              x-yc-apigateway-integration:
                type: cloud_functions
                function_id: <function ID>
                service_account_id: <service account ID>
      EOT
    }
    

    For more information about the resource parameters in Terraform, see the provider documentation.

  2. Make sure that the configuration files are correct.

    1. In the command line, go to the directory where you created the configuration file.

    2. Run the check using the command:

      terraform plan
      

    If the configuration is described correctly, the terminal displays a list of created resources and their parameters. If there are errors in the configuration, Terraform points them out.

  3. Deploy the cloud resources.

    1. If the configuration doesn't contain any errors, run the command:

      terraform apply
      
    2. Confirm the resource creation: type yes in the terminal and press Enter.

      Afterwards, all the necessary resources are created in the specified folder. You can verify that the resources are there and properly configured in the management console or using the following CLI command:

      yc serverless api-gateway get <API gateway name>
      

Access the function via the API gateway

Note

For the API gateway to be able to invoke a function, make it public or specify in the specification the service account that has rights to invoke a function.

Access the API gateway:

curl https://falrnjna8r5vj88ero6a.apigw.yandexcloud.net/numbers

Result:

[0, 1, 2]

See also

  • Concepts when using the service.
  • Step-by-step instructions for managing API gateways.

Was the article helpful?

Language / Region
© 2022 Yandex.Cloud LLC
In this article:
  • Before you begin
  • Create an API gateway
  • Access the API gateway
  • Add an integration with the function
  • Create a function
  • Extend the API gateway specification
  • Access the function via the API gateway