Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

x-yc-apigateway-integration:cloud_ydb extension

Written by
Updated at January 22, 2025

x-yc-apigateway-integration:cloud_ydb enables operations with document tables in Yandex Managed Service for YDB. To work with YDB, use Document API that is compatible with Amazon's DynamoDB.

You can add an extension to a specification using the specification constructor.

Supported operations

Operation Supported parameters What API Gateway returns in JSON format
if the operation is successful
PutItem table_name Element saved in the table
GetItem table_name
key		 Element read from table
UpdateItem table_name
key
update_expression
expression_attribute_values		 Element updated in the table
DeleteItem table_name
key		 Element deleted from the table
Scan table_name
limit
exclusive_start_key		 A list of elements read from the table

To convert the request body into an associative array with values of the AttributeValue type and place it into the Item parameter when performing the PutItem operation, provide that request body in JSON format.

If an object in JSON format comes in the request body for an UpdateItem operation, the AttributeUpdates set of changes will be generated from its fields and substituted into the relevant operation parameter.

Supported parameters

The table below lists the parameters specific to API Gateway API gateways. You can find the description of other parameters in the OpenAPI 3.0 specification.

Parameter Type Required Parameter
substitution		 Description
action string Yes No Operation in progress. Possible values: PutItem, GetItem, UpdateItem, DeleteItem, and Scan.
database string Yes No Relative path to the database.
service_account_id string Yes No Service account ID. Used for authorization when performing a database operation. If you omit the parameter, the service_account_id top-level parameter value will be used.
table_name string Yes Yes Name of the table with which the operation is performed.
key string No Yes Primary key of the element with which the operation is performed. This is a set of attributes and their values in JSON format. You must specify all key attributes. Attribute values are automatically converted to objects of the AttributeValue type. It is used in the GetItem, UpdateItem, and DeleteItem operations.
update_expression string No Yes Expression that specifies how and which attributes must be updated. Used in the UpdateItem operation.
expression_attribute_values string No Yes Alias that can be used in update_expression instead of the attribute value. It must start with a colon (:). Used in the UpdateItem operation.
limit string No Yes Maximum number of elements read. Used in the Scan operation.
exclusive_start_key string No Yes Primary key of the element from which the search starts. This is a set of attributes and their values in JSON format. Attribute values are automatically converted to objects of the AttributeValue type. Used in the Scan operation.

Specification examples

Extension specification

Here is an example of the REST API service that enables you to create, obtain, update, and delete movie entities:

openapi: 3.0.0
info:
  title: Movies API
  version: 1.0.0
servers:
  - url: https://d5dm1lba80md********.i9******.apigw.yandexcloud.net
paths:
  /movies:
    get:
      description: Get movies
      x-yc-apigateway-integration:
        type: cloud_ydb
        action: Scan
        database: /ru-central1/b3g1emj917**********/etn1f5fa8f**********
        table_name: movie
        limit: '{limit}'
        exclusive_start_key: '{"id": "{from}"}'
      operationId: getMovies
      parameters:
        - description: Identifier from which will be queried movies in ascending order
          explode: true
          in: query
          name: from
          required: true
          schema:
            type: string
          style: form
        - description: Maximum number of movies in response
          explode: true
          in: query
          name: limit
          required: false
          schema:
            default: 10.0
            type: number
          style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Movie'
                type: array
          description: Movies
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
    post:
      description: Create movie
      x-yc-apigateway-integration:
        type: cloud_ydb
        action: PutItem
        database: /ru-central1/b1g1emj927**********/etn1f4fa4f**********
        table_name: movie
      operationId: createMovie
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Movie'
        description: Movie to create
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movie'
          description: Created or updated movie
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
  /movies/{movieId}:
    delete:
      description: Delete movie by id
      x-yc-apigateway-integration:
        type: cloud_ydb
        action: DeleteItem
        database: /ru-central1/b1g1emj927**********/etn1f4fa4f**********
        table_name: movie
        key: '{"id": "{movieId}"}'
      operationId: deleteMovieById
      parameters:
        - description: Identifier of movie
          explode: false
          in: path
          name: movieId
          required: true
          schema:
            type: string
          style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movie'
          description: Deleted movie
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
    get:
      description: Get movie by id
      x-yc-apigateway-integration:
        type: cloud_ydb
        action: GetItem
        database: /ru-central1/b1g1emj927**********/etn1f4fa4f**********
        table_name: movie
        key: '{"id": "{movieId}"}'
      operationId: getMovieById
      parameters:
        - description: Identifier of movie
          explode: false
          in: path
          name: movieId
          required: true
          schema:
            type: string
          style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movie'
          description: Movie
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
    put:
      description: Update movie by id
      x-yc-apigateway-integration:
        type: cloud_ydb
        action: UpdateItem
        database: /ru-central1/b1g1emj927**********/etn1f4fa4f**********
        table_name: movie
        key: '{"id": "{movieId}"}'
      operationId: updateMovieById
      parameters:
        - description: Identifier of movie
          explode: false
          in: path
          name: movieId
          required: true
          schema:
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Movie'
        description: Movie or attributes to update
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movie'
          description: Updated movie
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
components:
  schemas:
    Movie:
      properties:
        year:
          type: integer
        id:
          type: string
        title:
          type: string
      required:
        - id
        - title
        - year
      type: object
    Error:
      properties:
        message:
          type: string
      required:
        - message
      type: object
x-yc-apigateway:
  service_account_id: ajent55o2h**********

Specification for tables with multiple primary keys

If you use tables with multiple primary keys, describe each one in the specification, and specify the values from both columns in your request. The example below shows a request to the staff table. It contains information about the company employees and a key consisting of two columns: FirstName and LastName.

API Gateway specification example:

openapi: 3.0.0
info:
  title: Staff API
  version: 1.0.0
servers:
  - url: https://d5dm1lba80md********.i9******.apigw.yandexcloud.net
paths:
  /staff:
    get:
      description: Get member info by first and last name
      x-yc-apigateway-integration:
        type: cloud_ydb
        action: GetItem
        database: /ru-central1/b1g1emj927**********/etn1f4fa4f**********
        table_name: staff
        key: '{"FirstName": "{FirstName}", "LastName": "{LastName}"}'
      operationId: getStaffMemberById
      parameters:
        - description: First name of member
          explode: false
          in: query
          name: FirstName
          required: true
          schema:
            type: string
          style: simple
        - description: Last name of member
          explode: false
          in: query
          name: LastName
          required: true
          schema:
            type: string
          style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
          description: success
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
          description: Got member
components:
  schemas:
    success:
      properties:
        id:
          type: string
x-yc-apigateway:
  service_account_id: ajent55o2h**********

Here is how the request for information on the John Doe employee will look like:

curl \
  --request GET \
  --header "Authorization: Bearer `yc iam create-token`" \
  "https://d5dm1lba80md********.i9******.apigw.yandexcloud.net/staff?FirstName=Ivan&LastName=Ivanov"

Where:

  • staff: Table the request is addressed to.
  • FirstName: First part of the key.
  • LastName: Second part of the key.

This will return information on the employee.

Previous
Message Queue
Next
Greedy parameters