REST API определяет набор функций, к которым разработчики могут совершать запросы и получать ответы. Взаимодействие происходит по протоколу HTTP. Преимуществом такого подхода является широкое распространение протокола HTTP, поэтому REST API можно использовать практически из любого языка программирования.
Для запросов с веб-клиентов - клиентской части социального приложения или от сайта существуют JS API и Flash-библиотека, которые более удобны и просты в использовании.
Все вызовы методов API - это GET или POST HTTP-запросы к URL с некоторым набором параметров. Кодировка результата - UTF-8.
Данные запроса могут передаваться в виде query-строки (после знака «?») при использовании метода GET, либо в теле POST-запроса. В случае GET-запроса, параметры должны быть закодированы с помощью URL encoding.
На данный момент, API не делает различий между GET и POSTзапросами. Тем не менее, существует ограничение на длину URL запроса - 2048 символов.
В каждом запросе должен присутствовать набор обязательных параметров. Также для каждой функции в ее документации определены дополнительные параметры, нужные только для этой функции. Текстовые значения параметров должны быть переданы в кодировке UTF-8. Одинаковые для всех функций параметры перечислены в таблице ниже (Таблица 16).
Таблица 16 Параметры функций
Имя | Тип | Описание |
|---|---|---|
method | string | Название вызываемого метода, например, users.getinfo; обязательный параметр |
app_id | int | Идентификатор приложения; обязательный параметр |
sig | string | Подпись запроса; обязательный параметр |
session_key | string | Сессия текущего пользователя |
uid | uint64 | Идентификатор пользователя, для которого вызывается метод; данный аргумент должен быть указан, если не указан session_key |
secure | bool | Флаг, обозначающий, что запрос идет по защищенной схеме «сервер-сервер»; возможные значения: 1 или 0; по-умолчанию 0 |
format | string | Формат выдачи ответа API; возможные значения: xml или json; по умолчанию json |
Параметры session_key и uid отвечают за авторизацию, то есть от лица какого пользователя происходит запрос. В зависимости от этого одна и та же функция в одном и том же приложении может возвращать немного разные результаты, например, когда один пользователь имеет доступ к различным закрытым данным, а другой нет. session_key используется для выполнения запросов по схеме «клиент-сервер», а uid - по схеме «сервер-сервер».
Сессия (session_key) получается при каждом новом сеансе работы пользователя с вашим приложением или сайтом. При последующих заходах того же пользователя это значение будет другим, поэтому сохранять его не надо. Значение session_key получается в зависимости от того, как используется REST API. Если используется API в клиенте социального приложения, session_key приходит в параметрах запроса, если интегрируются API для сайтов, сессия получается в процессе логина. В любом случае, после получения session_key, можно передать это значение на сервер, чтобы осуществлять вызовы функций API с сервера от лица текущего пользователя.
Схема клиент-сервер предназначена для случаев, когда REST API используется из клиента социального приложения, клиентского кода сайта или отдельного мобильного или desktop - приложения.
Если используется схема клиент-сервер, то в параметрах запроса secure=0 и sig рассчитывается по следующему алгоритму:
sig = md5(uid + params + private_key)
Значение params - это конкатенация пар «имя=значение» отсортированных в алфавитном порядке по «имя», где «имя» - это название параметра, передаваемого в функцию API, «значение» - значение параметра. Разделитель в конкатенации не используется. Параметр sig при расчете подписи не учитывается, все остальные параметры запроса должны учитываться при расчете.
Значение uid - идентификатор текущего пользователя приложения. Значение private_key можно взять из настроек приложения.
Схема сервер-сервер является более надежной. Некоторые запросы, которые подразумевают согласие пользователя, можно выполнить только по схеме клиент-сервер. В случае невозможности выполнения запроса по схеме сервер-сервер, вернется соответствующая ошибка.
Схема сервер-сервер использует отдельный ключ secret_key. При использовании схемы сервер-сервер, в параметрах запроса параметр secure=1 и значение параметра sig рассчитывается следующим образом:
sig = md5(params + secret_key)
В данном приложении описываются XML-RPC методы, использующиеся СГУ. Каждое описание состоит их имени метода и его входных и выходных значений.
Все ответы XML-RPC имеют общую структуру, приведенную в таблице ниже (Таблица 17).
Таблица 17 Структура ответов XML-RPC
Данные | Тип данных | Описание |
|---|---|---|
Вывод | Boolean | True или false в случае успешного или неуспешного завершения. |
Вывод | String | Если возникает ошибка, выводится сообщение об ошибке |
Вывод | Int | Код ошибки |
Вывод всегда состоит из трёх значений. Первое и третье являются фиксированными, второе содержит сообщение об ошибке только в случае сбоя. Код ошибки содержит одно из значений, приведенных в таблице ниже (Таблица 18).
Таблица 18 Коды ошибок
Значение | Код | Описание |
|---|---|---|
0x0000 | SUCCESS | Успешный ответ |
0x0100 | AUTHENTICATION | Пользователь не может быть аутентифицирован. |
0x0200 | AUTHORIZATION | Пользователь не имеет права выполнять запрошенное действие |
0x0400 | NO_EXISTS | Запрошенный ресурс не существует. |
0x0800 | ACTION | Ошибка состояния для выполнения действия. |
0x1000 | XML_RPC_API | Неверные параметры, например, параметр должен быть «1» или «2», а получено значение «3». |
0x2000 | INTERNAL | Внутренняя ошибка, например, ресурс не может быть загружен из БД. |
А.1. Запросы авторизации
СГУ имеет интерфейс, который упаковывает запросы XML-RPC. Для каждого запроса XML-RPC аутентифицируется токен сеанса, и после этого диспетчер запросов генерирует запрос авторизации, который может включать более одной операции. В таблицах ниже описаны эти запросы из разных команд интерфейса (Таблица 19 - Таблица 30).
Таблица 19 Команда Onevm
Команда onevm | XML-RPC метод | Запрос |
|---|---|---|
deploy | one.vm.deploy | VM:ADMIN HOST:MANAGE |
boot terminate suspend hold stop resume release poweroff reboot | one.vm.action | VM:MANAGE |
resched unresched | one.vm.action | VM:ADMIN |
migrate | one.vm.migrate | VM:ADMIN HOST:MANAGE |
disk-saveas | one.vm.disksaveas | VM:MANAGE IMAGE:CREATE |
disk-snapshot-create | one.vm.disksnapshotcreate | VM:MANAGE IMAGE:MANAGE |
disk-snapshot-delete | one.vm.disksnapshotdelete | VM:MANAGE IMAGE:MANAGE |
disk-snapshot-revert | one.vm.disksnapshotrevert | VM:MANAGE |
disk-attach | one.vm.attach | VM:MANAGE IMAGE:USE |
disk-detach | one.vm.detach | VM:MANAGE |
disk-resize | one.vm.diskresize | VM:MANAGE |
nic-attach | one.vm.attachnic | VM:MANAGE NET:USE |
nic-detach | one.vm.detachnic | VM:MANAGE |
create | one.vm.allocate | VM:CREATE IMAGE:USE NET:USE |
show | one.vm.info | VM:USE |
chown chgrp | one.vm.chown | VM:MANAGE [USER:MANAGE] [GROUP:USE] |
chmod | one.vm.chmod | VM:<MANAGE/ADMIN> |
rename | one.vm.rename | VM:MANAGE |
snapshot-create | one.vm.snapshotcreate | VM:MANAGE |
snapshot-delete | one.vm.snapshotdelete | VM:MANAGE |
snapshot-revert | one.vm.snapshotrevert | VM:MANAGE |
resize | one.vm.resize | VM:MANAGE |
update | one.vm.update | VM:MANAGE |
recover | one.vm.recover | VM:ADMIN |
save | – (ruby method) | VM:MANAGE IMAGE:CREATE TEMPLATE:CREATE |
updateconf | one.vm.updateconf | VM:MANAGE |
list top | one.vmpool.info | VM:USE |
– | one.vm.monitoring | VM:USE |
Таблица 20 Команда Onetemplate
Команда onetemplate | XML-RPC метод | Запрос |
|---|---|---|
update | one.template.update | TEMPLATE:MANAGE |
instantiate | one.template.instantiate | TEMPLATE:USE [IMAGE:USE] [NET:USE] |
create | one.template.allocate | TEMPLATE:CREATE |
clone | one.template.clone | TEMPLATE:CREATE TEMPLATE:USE |
delete | one.template.delete | TEMPLATE:MANAGE |
show | one.template.info | TEMPLATE:USE |
chown chgrp | one.template.chown | TEMPLATE:MANAGE [USER:MANAGE] [GROUP:USE] |
chmod | one.template.chmod | TEMPLATE:<MANAGE/ADMIN> |
rename | one.template.rename | TEMPLATE:MANAGE |
list top | one.templatepool.info | TEMPLATE:USE |
Таблица 21 Команда Onehost
Команда onehost | XML-RPC метод | Запрос |
|---|---|---|
enable disable offline | one.host.status | HOST:ADMIN |
update | one.host.update | HOST:ADMIN |
create | one.host.allocate | HOST:CREATE [CLUSTER:ADMIN] |
delete | one.host.delete | HOST:ADMIN |
rename | one.host.rename | HOST:ADMIN |
show | one.host.info | HOST:USE |
list top | one.hostpool.info | HOST:USE |
Таблица 22 Команда onecluster
Команда onecluster | XML-RPC метод | Запрос |
|---|---|---|
create | one.cluster.allocate | CLUSTER:CREATE |
delete | one.cluster.delete | CLUSTER:ADMIN |
update | one.cluster.update | CLUSTER:MANAGE |
addhost | one.cluster.addhost | CLUSTER:ADMIN HOST:ADMIN |
delhost | one.cluster.delhost | CLUSTER:ADMIN HOST:ADMIN |
adddatastore | one.cluster.adddatastore | CLUSTER:ADMIN DATASTORE:ADMIN |
deldatastore | one.cluster.deldatastore | CLUSTER:ADMIN DATASTORE:ADMIN |
addvnet | one.cluster.addvnet | CLUSTER:ADMIN NET:ADMIN |
delvnet | one.cluster.delvnet | CLUSTER:ADMIN NET:ADMIN |
rename | one.cluster.rename | CLUSTER:MANAGE |
show | one.cluster.info | CLUSTER:USE |
list | one.clusterpool.info | CLUSTER:USE |
Таблица 23 Команда onegroup
Команда onegroup | XML-RPC метод | Запрос |
|---|---|---|
create | one.group.allocate | GROUP:CREATE |
delete | one.group.delete | GROUP:ADMIN |
show | one.group.info | GROUP:USE |
update | one.group.update | GROUP:MANAGE |
addadmin | one.group.addadmin | GROUP:MANAGE USER:MANAGE |
deladmin | one.group.deladmin | GROUP:MANAGE USER:MANAGE |
quota | one.group.quota | GROUP:ADMIN |
list | one.grouppool.info | GROUP:USE |
– | one.groupquota.info | – |
defaultquota | one.groupquota.update | Только для пользователей из группы «oneadmin» |
Таблица 24 Команда onevdc
Команда onevdc | XML-RPC метод | Запрос |
|---|---|---|
create | one.vdc.allocate | VDC:CREATE |
rename | one.vdc.rename | VDC:MANAGE |
delete | one.vdc.delete | VDC:ADMIN |
update | one.vdc.update | VDC:MANAGE |
show | one.vdc.info | VDC:USE |
list | one.vdcpool.info | VDC:USE |
addgroup | one.vdc.addgroup | VDC:ADMIN GROUP:ADMIN |
delgroup | one.vdc.delgroup | VDC:ADMIN GROUP:ADMIN |
addcluster | one.vdc.addcluster | VDC:ADMIN CLUSTER:ADMIN ZONE:ADMIN |
delcluster | one.vdc.delcluster | VDC:ADMIN CLUSTER:ADMIN ZONE:ADMIN |
addhost | one.vdc.addhost | VDC:ADMIN HOST:ADMIN ZONE:ADMIN |
delhost | one.vdc.delhost | VDC:ADMIN HOST:ADMIN ZONE:ADMIN |
adddatastore | one.vdc.adddatastore | VDC:ADMIN DATASTORE:ADMIN ZONE:ADMIN |
deldatastore | one.vdc.deldatastore | VDC:ADMIN DATASTORE:ADMIN ZONE:ADMIN |
addvnet | one.vdc.addvnet | VDC:ADMIN NET:ADMIN ZONE:ADMIN |
delvnet | one.vdc.delvnet | VDC:ADMIN NET:ADMIN ZONE:ADMIN |
Таблица 25 Команда onevnet
Команда onevnet | XML-RPC метод | Запрос |
|---|---|---|
addar | one.vn.add_ar | NET:ADMIN |
rmar | one.vn.rm_ar | NET:ADMIN |
free | one.vn.free_ar | NET:MANAGE |
reserve | one.vn.reserve | NET:USE |
updatear | one.vn.update_ar | NET:MANAGE |
hold | one.vn.hold | NET:MANAGE |
release | one.vn.release | NET:MANAGE |
update | one.vn.update | NET:MANAGE |
create | one.vn.allocate | NET:CREATE [CLUSTER:ADMIN] |
delete | one.vn.delete | NET:MANAGE |
show | one.vn.info | NET:USE |
chown chgrp | one.vn.chown | NET:MANAGE [USER:MANAGE] [GROUP:USE] |
chmod | one.vn.chmod | NET:<MANAGE/ADMIN> |
rename | one.vn.rename | NET:MANAGE |
list | one.vnpool.info | NET:USE |
lock | one.vn.lock | NET:MANAGE |
unlock | one.vn.unlock | NET:MANAGE |
Таблица 26 Команда oneuser
Команда oneuser | XML-RPC метод | Запрос |
|---|---|---|
create | one.user.allocate | USER:CREATE |
delete | one.user.delete | USER:ADMIN |
show | one.user.info | USER:USE |
passwd | one.user.passwd | USER:MANAGE |
login | one.user.login | USER:MANAGE |
update | one.user.update | USER:MANAGE |
chauth | one.user.chauth | USER:ADMIN |
quota | one.user.quota | USER:ADMIN |
chgrp | one.user.chgrp | USER:MANAGE GROUP:MANAGE |
addgroup | one.user.addgroup | USER:MANAGE GROUP:MANAGE |
delgroup | one.user.delgroup | USER:MANAGE GROUP:MANAGE |
encode | – | – |
list | one.userpool.info | USER:USE |
– | one.userquota.info | – |
defaultquota | one.userquota.update | Ony for users in the oneadmin group |
Таблица 27 Команда onedatastore
Команда onedatastore | XML-RPC метод | Запрос |
|---|---|---|
create | one.datastore.allocate | DATASTORE:CREATE [CLUSTER:ADMIN] |
delete | one.datastore.delete | DATASTORE:ADMIN |
show | one.datastore.info | DATASTORE:USE |
update | one.datastore.update | DATASTORE:MANAGE |
Rename | one.datastore.rename | DATASTORE:MANAGE |
Chown chgrp | one.datastore.chown | DATASTORE:MANAGE [USER:MANAGE] [GROUP:USE] |
chmod | one.datastore.chmod | DATASTORE:<MANAGE / ADMIN> |
Enable disable | one.datastore.enable | DATASTORE:MANAGE |
list | one.datastorepool.info | DATASTORE:USE |
Таблица 28 Команда oneimage
Команда oneimage | XML-RPC метод | Запрос |
|---|---|---|
persistent nonpersistent | one.image.persistent | IMAGE:MANAGE |
enable disable | one.image.enable | IMAGE:MANAGE |
chtype | one.image.chtype | IMAGE:MANAGE |
snapshot-delete | one.image.snapshotdelete | IMAGE:MANAGE |
snapshot-revert | one.image.snapshotrevert | IMAGE:MANAGE |
snapshot-flatten | one.image.snapshotflatten | IMAGE:MANAGE |
update | one.image.update | IMAGE:MANAGE |
create | one.image.allocate | IMAGE:CREATE DATASTORE:USE |
clone | one.image.clone | IMAGE:CREATE IMAGE:USE DATASTORE:USE |
delete | one.image.delete | IMAGE:MANAGE |
show | one.image.info | IMAGE:USE |
chown chgrp |
| IMAGE:MANAGE [USER:MANAGE] [GROUP:USE] |
chmod | one.image.chmod | IMAGE:<MANAGE / ADMIN> |
rename | one.image.rename | IMAGE:MANAGE |
list top | one.imagepool.info | IMAGE:USE |
lock | one.image.lock | IMAGE:MANAGE |
unlock | one.image.unlock | IMAGE:MANAGE |
Таблица 29 Команда onemarket
Команда onemarket | XML-RPC метод | Запрос |
|---|---|---|
update | one.market.update | MARKETPLACE:MANAGE |
create | one.market.allocate | MARKETPLACE:CREATE |
delete | one.market.delete | MARKETPLACE:MANAGE |
show | one.market.info | MARKETPLACE:USE |
chown chgrp | one.market.chown | MARKETPLACE:MANAGE [USER:MANAGE] [GROUP:USE] |
chmod | one.market.chmod | MARKETPLACE:<MANAGE / ADMIN> |
rename | one.market.rename | MARKETPLACE:MANAGE |
enable disable | one.market.enable | MARKETPLACE:MANAGE |
list | one.marketpool.info | MARKETPLACE:USE |
Таблица 30 Команда onemarketapp
Команда onemarketapp | XML-RPC метод | Запрос |
|---|---|---|
create | one.marketapp.allocate | MARKETPLACEAPP:CREATE MARKETPLACE:USE |
export | (ruby method) | MARKETPLACEAPP:USE IMAGE:CREATE DATASTORE:USE [TEMPLATE:CREATE] |
download | (ruby method) | MARKETPLACEAPP:USE |
enable disable | one.marketapp.enable | MARKETPLACEAPP:MANAGE |
update | one.marketapp.update | MARKETPLACEAPP:MANAGE |
delete | one.marketapp.delete | MARKETPLACEAPP:MANAGE |
show | one.marketapp.info | MARKETPLACEAPP:USE |
chown chgrp | one.marketapp.chown | MARKETPLACEAPP:MANAGE [USER:MANAGE] [GROUP:USE] |
chmod | one.marketapp.chmod | MARKETPLACEAPP:<MANAGE / ADMIN> |
rename | one.marketapp.rename | MARKETPLACEAPP:MANAGE |
lock | one.marketapppool.info | MARKETPLACEAPP:USE |
list | one.marketapp.lock | MARKETPLACEAPP:MANAGE |
unlock | one.marketapp.unlock | MARKETPLACEAPP:MANAGE |