[Yandex Cloud documentation](../../index.md) > [Yandex API Gateway](../index.md) > Getting started

# Getting started with API Gateway

Follow this guide to create and test different types of extensions. First, you will set up an [API gateway](../concepts/index.md) to get a [static response](../concepts/extensions/dummy.md) and then add an integration for [invoking a function](../concepts/extensions/cloud-functions.md). You will need [curl](https://curl.haxx.se) to access the API gateway.

## Getting started {#before-you-begin}

To get started in Yandex Cloud:
1. Log in to the [management console](https://console.yandex.cloud). If not signed up yet, navigate to the management console and follow the on-screen instructions.
1. On the [**Yandex Cloud Billing**](https://center.yandex.cloud/billing/accounts) page, make sure you have a [billing account](../../billing/concepts/billing-account.md) linked and its [status](../../billing/concepts/billing-account-statuses.md) is `ACTIVE` or `TRIAL_ACTIVE`. If you do not have a billing account yet, [create one](../../billing/quickstart/index.md#create_billing_account).
1. If you do not have a [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) yet, [create one](../../resource-manager/operations/folder/create.md).

## Create an API gateway {#create-api-gw}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder where you want to create an API gateway.
  1. Navigate to **API Gateway**.
  1. Click **Create API gateway**.
  1. In the **Name** field, enter `numbers`.
  1. Optionally, in the **Description** field, provide a description.
  1. In the **Request execution timeout** field, specify the execution timeout. The value must not exceed the specified [limit](../concepts/limits.md#api-gw-limits).
  1. Under **Specification**, add the following specification:

      ```yaml
      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"
      ```

  1. Click **Create**.

- Terraform {#tf}

  With [Terraform](https://www.terraform.io/), 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](https://github.com/hashicorp/terraform/blob/main/LICENSE). The [Yandex Cloud provider for Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) is distributed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/) license.
  
  For more information about the provider resources, see the guides on the [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) website or [its mirror](../../terraform/index.md).

  If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform).
  
  
  To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../terraform/authentication.md) using the appropriate method.

  To create an API gateway:
  
  1. Specify the `yandex_api_gateway` properties in the configuration file:
  
     * `name`: API gateway name. The name format is as follows:
  
        * Length: between 3 and 63 characters.
        * It can only 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](../../resource-manager/concepts/labels.md) 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](../concepts/limits.md#api-gw-limits). This is an optional parameter. The default value is `300` seconds.
     * `spec`: API gateway specification.
  
     Here is an example of the configuration file structure:
  
     ```hcl
     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 on the properties of resources in Terraform, see [this provider guide](../../terraform/resources/api_gateway.md).
  
  1. Make sure the configuration files are correct.
  
     1. In the terminal, navigate to the directory where you created your configuration file.
     1. Run a check using this command:
  
        ```
        terraform plan
        ```
  
     If the configuration is correct, the terminal will display a list of the resources and their settings. Otherwise, Terraform will show any detected errors. 
  
  1. Deploy the cloud resources.
  
     1. If the configuration is correct, run this command:
  
        ```
        terraform apply
        ```
  
     1. Confirm creating the resources by typing `yes` and pressing **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](https://console.yandex.cloud) or these [CLI](../../cli/quickstart.md) commands:
  
        ```
        yc serverless api-gateway get <API_gateway_name>
        ```

{% endlist %}

## Access the API gateway {#api-gw-test}

1. In the [management console](https://console.yandex.cloud), select the folder containing the API gateway.
1. Navigate to **API Gateway** and click the API gateway you created.
1. Save the value of the **Default domain** field.
1. Install [curl](https://curl.haxx.se).
1. Access the API gateway using curl with one of the commands:

    * ```bash
      curl <service_domain>/hello?user=API
      ```

    * ```bash
      curl <service_domain>/hello
      ```

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

    Here is an example:
    
    ```bash
    curl https://d5dm1lba80md********.i9******.apigw.yandexcloud.net/hello?user=API
    ```

    Result:

    * ```text
      Hello, API!
      ```

    * ```text
      Hello, world!
      ```

## Add an integration with a function {#functions}

### Create a function {#function}

Create a [function](../../functions/concepts/function.md) to get a list of numbers. Read more about functions in the [Yandex Cloud Functions documentation](../../functions/index.md).

{% list tabs group=instructions %}

- Management console {#console}

  To create a function:
  1. Create a function:
      1. In the [management console](https://console.yandex.cloud), select the folder to create your function in.
      1. Click **Create resource**.
      1. Select **Function**.
      1. In the **Name** field, specify `list`.
      1. Click **Create**.
  1. Create a function version:
      1. Select the `nodejs18` runtime environment.
      1. Disable **Add files with code examples**.
      1. Click **Continue**.
      1. In the **Code source** field, select `Code editor`.
      1. Click **Create file** in the editor below.
          1. In the window that opens, enter `index.js` for the file name.
          1. Click **Create**.
      1. Paste the following code to `index.js`:

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

      1. In the **Entry point** field, specify `index.handler`.
      1. Click **Save changes**.
  1. [Make](../../functions/operations/function/function-public.md) your function public.

- Terraform {#tf}

  To create a function:
  1. Prepare a ZIP archive with the function code:
     1. Save the following code to a file named `index.js`:

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

     1. Add `index.js` to the `hello-js.zip` archive.
  1. Describe the `yandex_function` properties in the configuration file:

     ```hcl
     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 you change the function, update this string as well. The function will update when this string is updated.
     * `runtime`: Function [runtime](../../functions/concepts/runtime/index.md).
     * `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](../../iam/concepts/users/service-accounts.md) 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 on the properties of the `yandex_function` resource, see [this provider guide](../../terraform/resources/function.md).
  1. Make sure the configuration files are correct.
     1. In the terminal, navigate to the directory where you created your configuration file.
     1. Run a check using this command:

        ```bash
        terraform plan
        ```

     If the configuration is correct, the terminal will display a list of the resources and their settings. Otherwise, Terraform will show any detected errors.
  1. Deploy the cloud resources.
     1. If the configuration is correct, run this command:

        ```bash
        terraform apply
        ```

     1. Confirm creating the resources by typing `yes` and pressing **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](https://console.yandex.cloud) or these [CLI](../../cli/index.md) commands:

        ```bash
        yc serverless function list
        ```

{% endlist %}

### Extend the API gateway specification {#update}

Add function information to the API gateway specification.

{% list tabs group=instructions %}

- Management console {#console}

  To update an API gateway specification:
  1. In the [management console](https://console.yandex.cloud), select the folder where you want to update an API gateway.
  1. Navigate to **API Gateway**.
  1. In the API gateway row, click ![image](../../_assets/console-icons/ellipsis.svg) and select ![image](../../_assets/console-icons/pencil.svg) **Edit**.
  1. 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](../../iam/concepts/users/service-accounts.md) that has permissions to invoke the function.

     ```yaml
     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>
     ```

- Terraform {#tf}

  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:**

     ```hcl
     ...

       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 on the properties of resources in Terraform, see [this provider guide](../../terraform/resources/api_gateway.md).
  1. Make sure the configuration files are correct.
     1. In the terminal, navigate to the directory where you created your configuration file.
     1. Run a check using this command:

        ```bash
        terraform plan
        ```

     If the configuration is correct, the terminal will display a list of the resources and their settings. Otherwise, Terraform will show any detected errors.
  1. Deploy the cloud resources.
     1. If the configuration is correct, run this command:

        ```bash
        terraform apply
        ```

     1. Confirm creating the resources by typing `yes` and pressing **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](https://console.yandex.cloud) or these CLI commands:

        ```bash
        yc serverless api-gateway get <API_gateway_name>
        ```

{% endlist %}

### Access the function via the API gateway {#api-gw}

{% note info %}

To allow the API gateway to access the function, [make](../../functions/operations/function/function-public.md) it public or [specify](../concepts/extensions/cloud-functions.md) in the specification a [service account](../../iam/concepts/users/service-accounts.md) that has permissions to invoke the function.

{% endnote %}

Access the API gateway:

```bash
curl <service_domain>/numbers
```

Where `<service_domain>` is the value of the **Default domain** field you saved [earlier](#api-gw-test).

For example:

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

Result:

```text
[0, 1, 2]
```

#### Useful links {#see-also}

* [Service usage concepts](../concepts/index.md)
* [Step-by-step guides on managing API gateways](../operations/index.md)