Rest API Список клиентов, участвующих в программе лояльности - datawizio/pythonAPI GitHub Wiki

Список клиентов, участвующих в программе лояльности - это список покупателей, зарегистрировавшихся в программе лояльности сети магазинов. С помощью данного списка владельцы сети могут изучать предпочтения своих покупателей, мониторить частоту покупок, проводить маркетинговые акции и т.д. С помощью ресурса /loyalty/ можно получить доступ к списку клиентов, участвующих в программе лояльности, а также добавлять в справочник новых учасников программы.

С ресурсом /loyalty/ поддерживаются следующие команды:

• GET - получить одну страницу коллекции
• POST - добавить запись либо множество записей в Список клиентов, участвующих в программе лояльности
• OPTIONS - мета-информация по структуре объекта
• HEAD - аналог GET, но возвращается только заголовок ответа

Вид команды: GET http://api.datawiz.io/api/v1/loyalty/

• .json - Получить ответ с сервера в формате JSON
• .api - Получить ответ с сервера в формате HTML (тестовая площадка)

• format=json|api - аналог вышеуказанных суффиксов
• page_size={nn} - установить размер страницы равный {nn} объектов
• page={n} - скачать страницу {n}
• is_male={True,False} - отображать только: True-мужчин либо False-женщин
• search = {substring} - отображать только объекты, в полях client_name либо cardno которых найдено фрагмент "{substring}"
• ordering=cardno|client_name|client_birthday|identifier - сортировать по полю в алфавитном порядке (от меньшего - к большему)
• ordering=-cardno|-client_name|-client_birthday|-identifier - сортировать по полю в обратном порядке

ЗАМЕЧАНИЕ: identifier - означает сортировать по полю loyalty_id

Объект "коллекция" из четырех полей (count,next, previous,results).

Пример пустой коллекции, полученной в результате запроса:

GET http://api.datawiz.io/api/v1/loyalty/.json/?search=unknown-string

{
     "count": 0, 
     "next": null, 
     "previous": null, 
     "results": [] 
}

Пример коллекции из 2-х элементов: GET http://api.datawiz.io/api/v1/loyalty/?format=json&page_size=2:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"count": 3,
"next": "http://api.datawiz.io/api/v1/loyalty/?page=2&page_size=2",
"previous": null,
"results": [
{
"url": "http://api.datawiz.io/api/v1/loyalty/3/",
"loyalty_id": "3",
"cardno": "33",
"discount": "15.00",
"client_name": "Mariya",
"client_birthday": "1982-11-17T00:00:00",
"is_male": false,
},
{
"url": "http://api.datawiz.io/api/v1/loyalty/2/",
"loyalty_id": "2",
"cardno": "22",
"discount": "10.00",
"client_name": "Vlad",
"client_birthday": "1976-05-12T00:00:00",
"is_male": true,
}
]
}

В случае возникновения ошибки сервер возвращает ответ с соответствующим статусом, а также сообщением об ошибке, записанною в ключе detail:

HTTP 404 NOT FOUND 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 
{
"detail": "Not found"
}

Вид команды: POST http://api.datawiz.io/api/v1/loyalty/?format=json

• .json - Взаимодействовать с сервером в формате JSON
• .api - Взаимодействовать с сервером в формате HTML (тестовая площадка)

• `format=json - взаимодействовать с сервером в формате JSON
• `format=api - взаимодействовать с сервером в формате HTML (тестовая площадка)

В запросе передается JSON-объект типа словарь (dictionary), который описывает новый товар. Важны поля: loyalty_id, client_name, client_birthday. Порядок следования полей не принципиален.

Пример запроса на добавление одного нового объекта в Список клиентов, участвующих в программе лояльности: POST http://api.datawiz.io/api/v1/loyalty/.json

{
    "loyalty_id": "3", 
    "cardno": "33", 
    "discount": "15", 
    "client_name": "Mariya", 
    "client_birthday": "1982-11-17", 
    "is_male": false, 
}

При корректной обработке запроса сервер возвращает код статуса 201 и статус создания обьекта.

Пример ответа сервера:

HTTP 201 CREATED 
Content-Type: application/json 
Vary: Accept 
Location: http://api.datawiz.io/api/v1/loyalty/3/ 
Allow: GET, POST, HEAD, OPTIONS 
{
"updated": 0,
"inserted": 1
}

• Если объект с идентификатором loyalty_id уже существует на сервере, то указанный запрос заменит объект на сервере (replace) без предупреждения.
• Формат даты в поле client_birthday должен быть: 'YYYY-MM-DD'
• Все остальные поля могут быть null

В случае возникновения ошибки сервер возвращает ответ с соответствующим статусом, а также сообщениями об ошибке, записанными напротив имени поля, с которым эта ошибка связана. Если же ошибка касается не отдельного поля, а всего объекта, то сообщение об ошибке будет записано напротив ключа non_field_errors.

ПРИМЕЧАНИЕ. Каждое сообщение об ошибке представляет собой коллекцию (массив) символьных строк.

Пример ответа сервера при возникновении ошибки (поле client_birthday заполнено некоректно):

HTTP 400 BAD REQUEST
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"client_birthday": [
"Date has wrong format. Use one of these formats instead: YYYY[-MM[-DD]], YYYY-MM-DD"
]
}

Вид команды: POST http://api.datawiz.io/api/v1/loyalty/?format=json

• .json - Взаимодействовать с сервером в формате JSON
• .api - Взаимодействовать с сервером в формате HTML (тестовая площадка)

• `format=json - взаимодействовать с сервером в формате JSON
• `format=api - взаимодействовать с сервером в формате HTML (тестовая площадка)

В запросе передается JSON-объект типа список (list), который содержит один или более объект, описывающий новую единицу измерения. Передача на сервер объектов не по одиночке, а списком позволяет значительно увеличить скорость передачи объектов.

Пример запроса на пакетное добавление трёх новых объектов в Список клиентов, участвующих в программе лояльности: POST http://api.datawiz.io/api/v1/loyalty/.json

[
    {
        "loyalty_id": "10", 
        "cardno": "332", 
        "discount": "5", 
        "client_name": "Customer #1", 
        "client_birthday": "1970-10-20", 
        "is_male": true, 
    },
    {
        "loyalty_id": "11", 
        "cardno": "333", 
        "discount": "5", 
        "client_name": "Customer #2", 
        "client_birthday": "1994-04-12", 
        "is_male": false, 
    },
    {
        "loyalty_id": "12", 
        "cardno": "334", 
        "discount": "5", 
        "client_name": "Customer #3", 
        "client_birthday": "1985-06-11", 
        "is_male": false, 
    }
]

При корректной обработке запроса сервер возвращает код статуса 201 и статистику по добавленным/изменённым объектам.

Пример ответа сервера:

HTTP 201 CREATED
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"updated": 1,
"inserted": 2
}

• Если объект с идентификатором loyalty_id уже существует на сервере, то указанный запрос заменит объект на сервере (replace) без предупреждения.
• Формат даты в поле client_birthday должен быть: 'YYYY-MM-DD'
• Все остальные поля могут быть null

В случае возникновения ошибки сервер возвращает ответ с соответствующим статусом, а также сообщениями об ошибке, записанными в позиции объекта, в котором произошла ошибка, напротив имени поля, с которым эта ошибка связана. Если же ошибка касается не отдельного поля, а всего объекта, то сообщение об ошибке будет записано напротив ключа non_field_errors.

ПРИМЕЧАНИЕ. Каждое сообщение об ошибке представляет собой коллекцию (массив) символьных строк.

Пример ответа сервера при возникновении ошибки:

HTTP 400 BAD REQUEST
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
[
{},
{},
{
"discount": [
"Enter a number."
]
}
]

Как видно, ошибка произошла в третьем объекте, в поле name. Тут же указана и причина ошибки.

При выполнении данной команды возвращается такая JSON-структура:

OPTIONS /api/v1/loyalty/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"name": "Loyalty List",
"description": "Loyalty",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
],
"actions": {
"POST": {
"url": {
"type": "field",
"required": false,
"read_only": true
},
"loyalty_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"cardno": {
"type": "string",
"required": false,
"read_only": false,
"label": "cardno",
"max_length": 20
},
"discount": {
"type": "decimal",
"required": false,
"read_only": false,
"label": "discount"
},
"client_name": {
"type": "string",
"required": false,
"read_only": false,
"label": "client name",
"max_length": 200
},
"client_birthday": {
"type": "date",
"required": true,
"read_only": false
},
"is_male": {
"type": "boolean",
"required": false,
"read_only": false,
"label": "is male"
}
}
}
}

Воспользовавшись ресурсом /loyalty/{id} можно получить с сервера, модифицировать полностью и частично, а также удалить выбранный объект из Списка клиентов, участвующих в программе лояльности. Для выбора нужного объекта необходимо заменить {id} в URL ресурса на идентификатор из поля loyalty_id существующего объекта. Перечень существующих объектов и их идентификаторов можно получить воспользовавшись командой 'GET /loyalty/' (подробнее см.раздел "[11. Ресурс /loyalty/ (Список клиентов, участвующих в программе лояльности, Коллекция)]")

С ресурсом /loyalty/{id} поддерживаются следующие команды:

• GET - получить объект с loyalty_id={id}
• PUT - полностью заменить объект на сервере новым
• PATCH - изменить значение отдельных полей объекта
• DELETE - изъять из Списка клиентов, участвующих в программе лояльности объект с loyalty_id={id}
• OPTIONS - мета-информация по структуре объекта
• HEAD - аналог GET, но возвращается только заголовок ответа

Вид команды: GET http://api.datawiz.io/api/v1/loyalty/4 - получить объект с loyalty_id=4

• .json - Получить ответ с сервра в формате JSON
• .api - Получить ответ с сервра в формате HTML (тестовая площадка)

• format=json|api - установить формат данных. Аналог вышеуказанных суффиксов

При отправке на сервер команды GET /loyalty/{id} с пустым телом запроса сервер возвращает объект заданной структуры в формате JSON или сообщение об ошибке.

Например, GET http://api.datawiz.io/api/v1/loyalty/4/.json:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"url": "http://api.datawiz.io/api/v1/loyalty/4/",
"loyalty_id": "4",
"cardno": "331",
"discount": "3.00",
"client_name": "Mariya Dyvna",
"client_birthday": "1986-09-01T00:00:00",
"is_male": false,
}

В случае возникновения ошибки сервер возвращает ответ с соответствующим статусом, а также сообщением об ошибке, записанным в ключе detail:

HTTP 404 NOT FOUND 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 
{
"detail": "Not found"
}

Фактически данный запрос работает, как два последовательных запроса: 1 Удалить объект со старым loyalty_id = {id} (DELETE) 2 Создать новый объект с новым loyalty_id (POST)

Вид команды: PUT http://api.datawiz.io/api/v1/loyalty/4/.json - заменить объект с loyalty_id="4" на другой

• .json - Взаимодействовать с сервером в формате JSON
• .api - Взаимодействовать с сервером в формате HTML (тестовая площадка)

• format=json - взаимодействовать с сервером в формате JSON
• format=api - взаимодействовать с сервером в формате HTML (тестовая площадка)

В запросе передается JSON-объект с новым значением объекта

Важно только поле: loyalty_id, остальные поля могут быть null

Пример запроса на замену объекта в Справочнике единиц измерения:

PUT http://api.datawiz.io/api/v1/loyalty/4/.json

{
    "url": "http://api.datawiz.io/api/v1/loyalty/4/", 
    "loyalty_id": "4", 
    "cardno": "331", 
    "discount": "4.00", 
    "client_name": "Mariya Dyvna", 
    "client_birthday": "1986-09-01", 
    "is_male": false, 
}

Здесь замене подлежит поле discount. Нужно заметить, что при замене значения ключевого поля (identifier, в данном случае - loyalty_id), данное поле изменяется везде, и все связи сохраняются.

При корректной обработке запроса сервер возвращает код статуса 200 и измененный объект с заполненным полем url.

ПРИМЕЧАНИЕ. Если менялось поле loyalty_id, то и поле url также изменится!

Пример ответа сервера:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"url": "http://api.datawiz.io/api/v1/loyalty/4/",
"loyalty_id": "4",
"cardno": "331",
"discount": "4.00",
"client_name": "Mariya Dyvna",
"client_birthday": "1986-09-01",
"is_male": false,
}

• Если объект с идентификатором loyalty_id уже существует на сервере, то указанный запрос заменит объект на сервере (replace) без предупреждения.
• Формат даты в поле client_birthday должен быть: 'YYYY-MM-DD'
• Все остальные поля могут быть null

В случае возникновения ошибки сервер возвращает ответ с соответствующим статусом, а также сообщениями об ошибке, записанным напротив имени поля, с которым эта ошибка связана. Если же ошибка касается не отдельного поля, а всего объекта, то сообщение об ошибке будет записано напротив ключа non_field_errors.

ПРИМЕЧАНИЕ. Каждое сообщение об ошибке представляет собой коллекцию (массив) символьных строк.

Пример ответа сервера при возникновении ошибки (поле discount не номер, поле client_birthday - неверный формат даты):

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS
{
"discount": [
"Enter a number."
],
"client_birthday": [
"Date has wrong format. Use one of these formats instead: YYYY-MM-DD"
]
}

Команда PATCH используется, если нужно изменить отдельные поля объекта. Команда PATCH во всем похожа на команду PUT, только в ней можно указывать не весь объект, а только те поля, которые необходимо изменить.

Вид команды: PATCH http://api.datawiz.io/api/v1/loyalty/5/.json - заменить отдельные поля объекта с loyalty_id=5 на другие

• .json - Взаимодействовать с сервером в формате JSON
• .api - Взаимодействовать с сервером в формате HTML (тестовая площадка)

• format=json - взаимодействовать с сервером в формате JSON
• format=api - взаимодействовать с сервером в формате HTML (тестовая площадка)

В запросе передается JSON-объект с новым значением отдельных полей объекта

Важно только поле loyalty_id. Остальные поля могут быть null.

Пример запроса на замену значения поля discount для объекта с loyalty_id=4:

PATCH http://api.datawiz.io/api/v1/loyalty/4/.json

{
    "discount": "5.00", 
}

При корректной обработке запроса сервер возвращает код статуса 200 и измененный объект с заполненным полем url.

ПРИМЕЧАНИЕ! Если менялось поле loyalty_id, то и поле url также изменится!

Пример ответа сервера:

HTTP 200 OK 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
"url": "http://api.datawiz.io/api/v1/loyalty/4/",
"loyalty_id": "4",
"cardno": "331",
"discount": "5.00",
"client_name": "Mariya Dyvna",
"client_birthday": "1986-09-01T00:00:00",
"is_male": false,
}

• Если объект с идентификатором loyalty_id уже существует на сервере, то указанный запрос заменит объект на сервере (replace) без предупреждения.
• Формат даты в поле client_birthday должен быть: 'YYYY-MM-DD'
• Все остальные поля могут быть null

В случае возникновения ошибки сервер возвращает ответ с соответствующим статусом, а также сообщениями об ошибке, записанным напротив имени поля, с которым эта ошибка связана. Если же ошибка касается не отдельного поля, а всего объекта, то сообщение об ошибке будет записано напротив ключа non_field_errors.

ПРИМЕЧАНИЕ. Каждое сообщение об ошибке представляет собой коллекцию (массив) символьных строк.

Пример ответа сервера при возникновении ошибки (поле client_birthday имеет неверный формат даты):

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS
{
"client_birthday": [
"Date has wrong format. Use one of these formats instead: YYYY-MM-DD"
]
}

Команда DELETE используется для извлечения указанного объекта из Списка клиентов, участвующих в программе лояльности

Вид команды: DELETE http://api.datawiz.io/api/v1/loyalty/100/ - изъять обьект с loyalty_id=100

• .json - взаимодействовать с сервером в формате JSON
• .api - взаимодействовать с сервером в формате HTML (тестовая площадка)

• format=json - взаимодействовать с сервером в формате JSON
• format=api - взаимодействовать с сервером в формате HTML (тестовая площадка)

В запросе ничего передавать не нужно.

При корректной обработке запроса сервер возвращает код статуса 204 NO CONTENT.

Пример ответа сервера:

HTTP 204 NO CONTENT 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH

• Нельзя удалить единицу измерения, которая уже используется в Чеках

В случае возникновения ошибки сервер возвращает ответ с соответствующим статусом, а также сообщением об ошибке, записанным в ключе detail:

HTTP 404 NOT FOUND 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 
{
"detail": "Not found"
}

При выполнении данной команды возвращается такая JSON-структура:

OPTIONS /api/v1/loyalty/100/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"name": "Loyalty Instance",
"description": "Loyalty",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
],
"actions": {
"PUT": {
"url": {
"type": "field",
"required": false,
"read_only": true
},
"loyalty_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"cardno": {
"type": "string",
"required": false,
"read_only": false,
"label": "cardno",
"max_length": 20
},
"discount": {
"type": "decimal",
"required": false,
"read_only": false,
"label": "discount"
},
"client_name": {
"type": "string",
"required": false,
"read_only": false,
"label": "client name",
"max_length": 200
},
"client_birthday": {
"type": "date",
"required": true,
"read_only": false
},
"is_male": {
"type": "boolean",
"required": false,
"read_only": false,
"label": "is male"
}
}
}
}