Запросы и ответы

Аутентификация

При разработке Django-приложений для браузера, вы можете не думать об этом. Аутентификация будет происходить по ключу сессии так, как это обычно работает в Django.

Авторизованный доступ к выполнению методов из сторонних приложений и скриптов осуществляется по следующим правилам:

  1. Принимается Basic-авторизация в заголовке Authorization внутри POST или GET запросов.
  2. Принимается обычная авторизация только внутри POST запросов.
  3. После первого успешного ответа сервера, учётные данные не требуются если клиент поддерживает cookies.

Обычная авторизация - это передача в открытом виде параметров username и password непосредственно в POST запросе или внутри jsonData.

Структура запросов

Любой запрос должен содержать обязательный ключ method и необязательный language.

В POST-запросе дополнительно могут находится ключи: username, password.

Прочие ключи воспринимаются как параметры метода.

При использовании сложно-структурированных параметров, все ключи, за исключением language, должны быть упакованы в один jsonData (JSON закодированный как URL Encoding). Это возможно только с POST запросами.

Для передачи зарезервированных имён username, password и language в роли параметров для метода, вы должны обернуть все параметры в ключ kwargs внутри jsonData.

### GET ###
curl "http://localhost:8000/reports/api/?method=quickapi.test"
curl "http://localhost:8000/reports/api/?method=quickapi.test&code=302&redirect=/login/"
curl "http://localhost:8000/reports/api/?method=quickapi.test&language=ru"

### POST ###
curl "http://localhost:8000/reports/api/" -d "method=quickapi.test&language=en"
curl "http://localhost:8000/reports/api/" -d "method=quickapi.test&username=test&password=test"

### POST + JSON ###
curl "http://localhost:8000/reports/api/" -d "jsonData=%7B%22method%22%3A%22quickapi.test%22%2C%22kwargs%22%3A%7B%22code%22%3A301%7D%7D"
curl "http://localhost:8000/reports/api/" -d "jsonData=%7B%22method%22%3A%22quickapi.test%22%2C%22kwargs%22%3A%7B%22code%22%3A301%7D%7D&language=en"

Использование готовых клиентов

jQuery

<script src="/static/quickapi/3.5.0/js/jquery.quickapi.min.js"></script>
<script>
// возвращает quickapi.test по /api/
$.quickAPI();

// расширенное использование
$.quickAPI({
    url: "/api/",
    data: {
        method: "quickapi.test",
        kwargs: { code: 200},
    },
    type: "GET",    // `POST` по-умолчанию
    async: false,   // `true` по-умолчанию
    timeout: 1000,  // `3000` по-умолчанию
    language: 'ru', // `window.LANGUAGE_CODE` по-умолчанию
    simple_request: true // по-умолчанию возвращает jsonData
    callback: function(json, status, xhr) {},
    handlerShowAlert: function(head, msg, cls, cb) {},
})
</script>

Более подробный пример находится тут.

Python

from quickapi.client import BaseClient

kw = {
    'url': 'http://localhost:8000/reports/api/',
    # Можно установить все необходимые параметры:
    # `username`, `password`, `timeout`, `cookie_filename`...
}

# Один экземпляр для всех вызываемых методов
api = BaseClient(**kw)

# Включить печать заголовков ответа
api.print_info = True

# Не авторизованный пользователь
data = api.method('quickapi.test')

# Установка файла с cookies
api.set_cookiejar('cookies.txt')

api.username = 'login'
api.password = 'passw'

# Вы можете включить HTTP Basic авторизацию
api.use_basic_auth = True

# Попытка авторизации пользователя
data = api.method('quickapi.test')

# В дальнейшем авторизация будет происходить с помощью файлов cookie и данные лучше скрыть
api.username = None
api.password = None

data = api.method('quickapi.test', code=200)

# Тестовый вызов ошибок
data = api.method('quickapi.test', code=302)
data = api.method('quickapi.test', code=400)
data = api.method('quickapi.test', code=401)
data = api.method('quickapi.test', code=500)
data = api.method('quickapi.test', bugparam=1)
data = api.method('bug.method.name', code=200)

Структура ответов

Тип и структура вложенного объекта зависят от вызываемого метода. Но общая схема выглядит единообразно.

Стандартный ответ с данными (JSONResponse):

{
    "status": 200,
    "message": "OK",
    "data": null,
}

Переадресация (JSONRedirect):

{
    "status": 301,
    "message": "Moved Permanently",
    "data": {"Location": "/to-redirect/"},
}

Как вы могли заметить, всегда присутствуют ключи:

  • status - код ответа - тут могут быть ваши собственные коды, либо стандартные коды протокола HTTP;
  • message - небольшое сообщение, характризующее исполнение метода;
  • data - любые данные, которые вы хотите передать клиенту;