Basic principles

Yandex.Cloud APIs are based on the gRPC mechanism. Methods and data structures in APIs are described using Protocol Buffers (proto 3).

Yandex.Cloud services provide a JSON REST interface that you can access directly. REST is supported via the gRPC-JSON transcoder. Yandex.Cloud services use this mechanism to translate incoming HTTP requests into gRPC calls. The service translates the results of request handling into an HTTP response and returns it to the client.

Resource-based approach

APIs use a resource-based approach. The principles that apply to all Yandex.Cloud APIs are described below:

• Resources in APIs are VM instances, disks, images, and so on. Each resource has a unique ID.

• Two sets of methods are defined for managing resources in APIs:

  • Standard API methods allow you to perform CRUD operations: create, retrieve, update, and delete resources. Standard methods have the same semantics and work in the same way for all APIs.
  • Additional API methods enhance the functionality of standard methods. They can be used to perform operations such as attaching a disk, restarting a VM instance, and so on. The semantics of additional methods differs from that of standard ones.

• Any operations that change the state of a resource are asynchronous operations. When such operations are called, the server returns the Operation object. This object contains the state of the operation and the ID of the resource the operation is being performed on.

• Operations for creating, updating, and deleting resources support idempotence.