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


one.image.chown

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


 

  • Нет меток