API приложений Webasyst

Содержание...

Работа с API фреймворка Webasyst и всех установленных в нем приложений осуществляется через единую точку взаимодействия — api.php.

Авторизация основана на протоколе OAuth 2.0:

  1. Получаем токен авторизации (ключ доступа), указывая в запросе идентификаторы приложений, к API которых нужен доступ.
  2. Используя полученный токен, работаем с API-методами указанных приложений. При работе с методами API учитываются права доступа пользователя, для которого был выдан токен.

Теперь подробнее.

1. Получение токена (ключа доступа)

Используется немного модифицированная и упрощенная версия OAuth 2.0 http://oauth.net/2/.

Запрос на токен отправляет пользователя на сайт с установленным фреймворком Webasyst, где пользователь авторизуется со своими логином и паролем (логин и пароль пользователь вводит именно на сайте с установленным фреймворком, но не в приложении-клиенте, пытающемся получить токен). Пройдя авторизацию, пользователь разрешает или запрещает доступ к API.

Пример токена: b936356100e3883cabf59abed991d03d
Токен выдается только в случае разрешения доступа к API. Схема запроса на доступ от приложения следующая (далее выдержка из документации протокола OAuth 2.0):

A. Web Server Applications

Redirect users who wish to authenticate to
http://ACCOUNT_URL/api.php/auth?client_id=CLIENT_ID&client_name=CLIENT_NAME&response_type=code&scope=SCOPE&redirect_uri=REDIRECT_URI&format=FORMAT

If a user accepts, they will be redirected back to
REDIRECT_URL?code=CODE
otherwise
REDIRECT_URL?error=access_denied

Your server will make a request for
http://ACCOUNT_URL/api.php/token?client_id=CLIENT_ID&grant_type=authorization_code&redirect_uri=REDIRECT_URI&format=FORMAT

The response will be JSON or XML (&format=XML)

{"access_token": ACCESS_TOKEN}

or

<response>
        <access_token>ACCESS_TOKEN</access_token>
    </response>

B. Client applications

Redirect users who wish to authenticate to
http://ACCOUNT_URL/api.php/auth?client_id=CLIENT_ID&client_name=CLIENT_NAME&response_type=token&scope=SCOPE&redirect_uri=REDIRECT_URI&format=FORMAT

If a user accepts, they will be redirected back to
REDIRECT_URL#access_token=ACCESS_TOKEN
otherwise
REDIRECT_URL#error=access_denied

Пояснения к переменным

ACCOUNT_URL — URL корневой папки установки фреймворка Webasyst

CLIENT_ID — уникальный идентификатор приложения, например, XYZCompanyShopImportApp; для веб-приложений рекомендуется указывать домен, чтобы избежать возможных конфликтов; идентификатор приложения разработчик придумывает на свое усмотрение

CLIENT_NAME — название приложения, которое будет показано на странице запроса доступа

SCOPE — приложения, к которым нужен доступ, перечисленные через запятую, например, scope=shop,photos,blog

REDIRECT_URI — URL, на который будет перенаправлен пользователь после принятия или отказа от принятия предоставления доступа к данным приложений

CODE — одноразовый код, необходимый для получения токена; действителен в течение 5 минут

FORMAT — необязательный параметр, указывающий на формат обмен информацией; возможные варианты значений: xml или json; если параметр не указан, то по умолчанию используется json

2. Запросы к API

http://ACCOUNT_URL/api.php/APP_ID.METHOD?PARAMS&access_token=ACCESS_TOKEN&format=FORMAT

Например, http://localhost/api.php/shop.product.getInfo?id=4&access_token=ACCESS_TOKEN&format=xml

Альтернативный способ:

http://ACCOUNT_URL/api.php?app=APP_ID&method=METHOD&PARAMS&access_token=ACCESS_TOKEN&format=FORMAT

  • METHOD

    название метода, например, shop.category.getTree, stickies.sheet.getList

  • PARAMS

    набор параметров согласно описанию метода, например, parent_id=0&max_level=3

  • ACCESS_TOKEN

    токен, полученный при авторизации

  • RESPONSE

    необязательный параметр, указывающий на формат ответа; возможные варианты: xml, json (если не указан, то json)

  • APP_ID (в альтернативном способе вызова)

    идентификатор приложения, например, shop, stickies, photos, blog

  • FORMAT

    необязательный параметр, указывающий на формат обмен информацией; возможные варианты значений: xml или json; если параметр не указан, то по умолчанию используется json

В случае ошибки в ответе всегда будет доступно поле error:

JSON

{"error": "invalid_request"}

XML

<response>
    <error>invalid_request</error>
</response>

Коды ошибок (элемент error)

  • invalid_request

    неверно сфомированный запрос; дополнительная информация об ошибке указывается в поле error_description

  • access_denied

    для данного токена нет доступа к запрошенному методу

  • invalid_method

    вызов неизвестного метода API