Yandex Cloud
Search
Contact UsGet started
  • Blog
  • Pricing
  • Documentation
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • ML & AI
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Customer Stories
    • Gateway to Russia
    • Cloud for Startups
    • Education and Science
  • Blog
  • Pricing
  • Documentation
Yandex project
© 2025 Yandex.Cloud LLC
Yandex API Gateway
  • Getting started
  • Access management
  • Pricing policy
  • Terraform reference
  • Monitoring metrics
  • Audit Trails events
  • Release notes
  • FAQ

In this article:

  • Getting started
  • Create an API gateway
  • Access the API gateway
  • Add an integration with a function
  • Create a function
  • Extend the API gateway specification
  • Access the function via the API gateway

Getting started with API Gateway

Written by
Yandex Cloud
Improved by
Danila N.
Updated at May 26, 2025
  • Getting started
  • Create an API gateway
  • Access the API gateway
  • Add an integration with a function
    • Create a function
    • Extend the API gateway specification
    • Access the function via the API gateway

Follow this guide to create and test different types of extensions. First, you will set up an API gateway to get a static response and then add an integration for invoking a function. You will need curl to access the API gateway.

Getting startedGetting started

To get started in Yandex Cloud:

  1. Log in to the management console. If not signed up yet, navigate to the management console and follow the on-screen instructions.
  2. On the Yandex Cloud Billing page, make sure you have a billing account linked and its status is ACTIVE or TRIAL_ACTIVE. If you do not have a billing account yet, create one.
  3. If you do not have a folder yet, create one.

Create an API gatewayCreate an API gateway

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

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

  3. Click Create API gateway.

  4. In the Name field, specify numbers.

  5. Optionally, in the Description field, enter a description.

  6. In the Request execution timeout field, specify the execution timeout. The value must not exceed the set limit.

  7. In the Specification section, add the 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"
    
  8. Click Create.

With Terraform, you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.

Terraform is distributed under the Business Source License. The Yandex Cloud provider for Terraform is distributed under the MPL-2.0 license.

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

If you do not have Terraform yet, install it and configure its Yandex Cloud provider.

To create an API gateway:

  1. Describe yandex_api_gateway properties in the configuration file:

    • name: API gateway name. Follow these naming requirements:

      • It must be from 2 to 63 characters long.
      • It may contain lowercase Latin letters, numbers, and hyphens.
      • It must start with a letter and cannot end with a hyphen.
    • description: API gateway description.

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

    • execution_timeout: Request execution timeout. The value is specified in seconds and must not exceed the set limit. This is an optional parameter. The default value is 300 seconds.

    • spec: API gateway specification.

    Here is an example of the configuration file structure:

    resource "yandex_api_gateway" "test-api-gateway" {
      name        = "<API_gateway_name>"
      description = "<API_gateway_description>"
      labels      = {
        label       = "label"
        empty-label = ""
      }
      execution_timeout = "<request_execution_timeout>"
      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 resource properties in Terraform, see the relevant Terraform documentation.

  2. Make sure the configuration files are correct.

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

    2. Run a check using this command:

      terraform plan
      

    If the configuration is correct, the terminal will display a list of new resources with their properties. If the configuration contains any errors, Terraform will point them out.

  3. Deploy the cloud resources.

    1. If the configuration does not contain any errors, run this command:

      terraform apply
      
    2. Confirm creating the resources: type yes in the terminal and press Enter.

      This will create all the resources you need in the specified folder. You can check the new resources and their settings using the management console or these CLI commands:

      yc serverless api-gateway get <API_gateway_name>
      

Access the API gatewayAccess 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 API gateway you created.

  3. Save the value of the Default domain field.

  4. Install curl.

  5. Access the API gateway using curl with one of the commands:

    • curl <service_domain>/hello?user=API
      
    • curl <service_domain>/hello
      

    Where <service_domain> is the value of the Default domain field you saved earlier.

    Here is an example:

    curl https://d5dm1lba80md********.i9******.apigw.yandexcloud.net/hello?user=API
    

    Result:

    • Hello, API!
      
    • Hello, world!
      

Add an integration with a functionAdd an integration with a function

Create a functionCreate a function

Create a function to get a list of numbers. Read more about functions in the Yandex 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.
  2. Create a function version:
    1. Select the nodejs18 runtime environment.

    2. Disable Add files with code examples.

    3. Click Continue.

    4. In the Method field, select Code editor.

    5. Click Create file in the editor below.

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

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

    8. Click Save changes.

  3. Make your function public.

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 yandex_function properties in the configuration file:

    resource "yandex_function" "test-function" {
      name               = "test-function"
      description        = "Test function"
      user_hash          = "first-function"
      runtime            = "nodejs18"
      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: Any string to identify the function version. When the function changes, update this string, too. The function will update when this string is updated.
    • runtime: Function runtime environment.
    • entrypoint: Function name in the source code that will serve as an entry point to applications.
    • memory: Amount of memory allocated for the function, in MB.
    • execution_timeout: Function execution timeout.
    • service_account_id: ID of the service account to invoke the function under.
    • 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 yandex_function properties, see this Terraform article.

  3. Make sure the configuration files are correct.

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

    2. Run a check using this command:

      terraform plan
      

    If the configuration is correct, the terminal will display a list of new resources with their properties. If the configuration contains any errors, Terraform will point them out.

  4. Deploy the cloud resources.

    1. If the configuration does not contain any errors, run this command:

      terraform apply
      
    2. Confirm creating the resources: type yes in the terminal and press Enter.

      This will create all the resources you need in the specified folder. You can check the new resources and their settings using the management console or these CLI commands:

      yc serverless function list
      

Extend the API gateway specificationExtend 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.

    It now includes the /numbers method which uses the x-yc-apigateway-integration extension of the cloud_functions type to invoke a function by ID.

    To ensure the API gateway works properly, in the function_id parameter, specify the ID of the function to invoke. To enable the API gateway to access a private function, in the service_account_id parameter, specify a service account that has permissions 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 which uses the x-yc-apigateway-integration extension of the cloud_functions type to invoke a function by ID. In the spec section, update the API gateway specification by providing the following parameters:

    • function_id: Function ID.
    • service_account_id: ID of the service account with permissions to invoke the 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 resource properties in Terraform, see the relevant Terraform documentation.

  2. Make sure the configuration files are correct.

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

    2. Run a check using this command:

      terraform plan
      

    If the configuration is correct, the terminal will display a list of new resources with their properties. If the configuration contains any errors, Terraform will point them out.

  3. Deploy the cloud resources.

    1. If the configuration does not contain any errors, run this command:

      terraform apply
      
    2. Confirm creating the resources: type yes in the terminal and press Enter.

      After that, your resources will appear in the specified folder. You can check the new resources and their settings using the management console or these CLI commands:

      yc serverless api-gateway get <API_gateway_name>
      

Access the function via the API gatewayAccess the function via the API gateway

Note

To allow the API gateway to access the function, make it public or specify in the specification a service account that has permissions to invoke the function.

Access the API gateway:

curl <service_domain>/numbers

Where <service_domain> is the value of the Default domain field you saved earlier.

For example:

curl https://d5dm1lba80md********.i9******.apigw.yandexcloud.net/numbers

Result:

[0, 1, 2]

See alsoSee also

  • Service usage concepts.
  • Step-by-step guides on managing API gateways.

Was the article helpful?

Next
All guides
Yandex project
© 2025 Yandex.Cloud LLC