Getting started with 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:
- Log in to the management console. If you aren't registered, go to the management console and follow the instructions.
- On the billing page, make sure you linked a billing account and it has the
ACTIVE
orTRIAL_ACTIVE
status. If you don't have a billing account, create one.
- On the billing page, make sure you linked a billing account and it has the
- If you don't have a folder, create one.
Create an API gateway
-
In the management console, select the folder where you wish to create an API gateway.
-
In the list of services, select API Gateway.
-
Click Create API gateway.
-
In the Name field, enter
numbers
. -
(optional) In the Description field, enter a description.
-
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"
-
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:
-
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.
-
-
Make sure that the configuration files are correct.
-
In the command line, go to the directory where you created the configuration file.
-
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.
-
-
Deploy the cloud resources.
-
If the configuration doesn't contain any errors, run the command:
terraform apply
-
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
-
In the management console, select the folder containing the API gateway.
-
In the list of services, select API Gateway and click the name of the created API gateway.
-
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
-
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:
- Create a function:
- In the management console, select the folder to create your function in.
- Click Create resource.
- Select Function.
- In the Name field, specify
list
. - Click Create.
- Make your function public.
- Create the function version:
-
In the window that opens, select the function you created.
-
Under Latest version, click Create in editor.
-
In the window that opens, in the Runtime environment field, select
nodejs12
. -
In the Method field, select the code editor.
-
Click Create file in the editor below.
- In the window that opens, enter the
index.js
file name. - Click Create.
- In the window that opens, enter the
-
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]" }; };
-
In the Entry point field, enter
index.handler
. -
Click Create version.
-
To create a function:
-
Prepare a ZIP archive with the function code:
-
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]" }; };
-
Add
index.js
to thehello-js.zip
archive.
-
-
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. -
Make sure that the configuration files are correct.
-
In the command line, go to the directory where you created the configuration file.
-
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.
-
-
Deploy the cloud resources.
-
If the configuration doesn't contain any errors, run the command:
terraform apply
-
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:
-
In the management console, select the folder where you want to update an API gateway.
-
In the window that opens, select the API gateway and click .
-
In the menu that opens, click Edit.
-
Under Specification, add an extended version of the specification
The
/numbers
method, which uses thecloud_functions
typex-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 theservice_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:
-
Open the Terraform configuration file and add the
/numbers
method that uses thecloud_functions
typex-yc-apigateway-integration
extension to invoke a function by ID. Underspec
, 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.
-
Make sure that the configuration files are correct.
-
In the command line, go to the directory where you created the configuration file.
-
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.
-
-
Deploy the cloud resources.
-
If the configuration doesn't contain any errors, run the command:
terraform apply
-
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]