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"
}
}
}
}