Get started
Language / Region
© 2022 Yandex.Cloud LLC
Yandex API Gateway

Getting started with API Gateway

Written by

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

  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.

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.

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

Language / Region
© 2022 Yandex.Cloud LLC
In this article: