Basic principles
Yandex Cloud APIs are based on the gRPC mechanism. The API methods and data structures 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 of most Yandex Cloud services use a resource-based approach. How it works:
-
In APIs, resources are VMs, disks, images, etc. 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 signature and work in the same way for all APIs they are used in.
- Additional API methods enhance the functionality of standard methods. You can use them to attach a disk, restart a VM, and perform other operations. The signature of additional methods differs from that of standard ones.
-
Any operations that change the state of a resource are asynchronous signature operations. When they 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 idempotency.
Exceptions for the resource-based approach
- Yandex Object Storage API. Its architecture is compatible with the Amazon S3 API, so the Object Storage API operating principles do not always match those of the resource-based approach. For more information, see the documentation on the service.
- YandexGPT API, Yandex SpeechKit, Yandex Translate, and Yandex Vision OCR AI service API. The API of these services does not use Yandex Cloud resources and API requests are not idempotent.