Основные принципы
API Яндекс.Облака спроектированы на основе механизма gRPC. Для описания методов и структур данных в API используется Protocol Buffers (proto 3).
Сервисы Яндекс.Облака предоставляют JSON REST интерфейс, к которому можно обращаться напрямую. Поддержка REST осуществляется посредством механизма gRPC-JSON transcoder. С его помощью сервисы Яндекс.Облака преобразуют входящие HTTP-запросы в gRPC-вызовы. Результаты обработки запроса сервис преобразует в HTTP-ответ и отправляет его клиенту.
Ресурсо-ориентированный подход
В API используется ресурсо-ориентированный подход. Ниже описаны принципы, которые действуют для всех API Яндекс.Облака:
-
В качестве ресурсов в API выступают виртуальные машины, диски, образы и т. д. Каждый ресурс имеет уникальный идентификатор.
-
Для управления ресурсами в API определены два набора методов:
- Стандартные методы API позволяют выполнять CRUD-операции: создавать, получать, изменять и удалять ресурсы. Стандартные методы имеют одинаковую сигнатуру и работают одинаково для всех API.
- Дополнительные методы API расширяют функциональность стандартных методов. С их помощью можно выполнить такие операции, как подключить диск, перезапустить виртуальную машину и др. Сигнатура дополнительных методов отличается от сигнатуры стандартных методов.
-
Все операции, изменяющие состояние ресурса, имеют асинхронную сигнатуру. При вызове таких операций сервер возвращает объект Operation. Этот объект будет содержать состояние операции, а также идентификатор ресурса, над которым производится операция.
-
Операции на создание, изменение и удаление ресурсов поддерживают механизм идемпотентности.
Примечание
Архитектура Yandex Object Storage API обеспечивает совместимость с Amazon S3 API. Поэтому Object Storage API может не соответствовать концепциям, описанным в данном документе. Подробнее читайте в документации к сервису.