Запросы и ответы¶
Аутентификация¶
При разработке Django-приложений для браузера, вы можете не думать об этом. Аутентификация будет происходить по ключу сессии так, как это обычно работает в Django.
Авторизованный доступ к выполнению методов из сторонних приложений и скриптов осуществляется по следующим правилам:
- Принимается Basic-авторизация в заголовке
Authorization
внутриPOST
илиGET
запросов. - Принимается обычная авторизация только внутри
POST
запросов. - После первого успешного ответа сервера, учётные данные не требуются если клиент поддерживает
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 - любые данные, которые вы хотите передать клиенту;