Rest API Довідник касирів - datawizio/pythonAPI GitHub Wiki

13. Ресурс /cashiers/ (Довідник касирів, Колекція)

Довідник касирів - це загальний список касирів мережі магазинів (без прив'язки до конкретного магазину). З допомогою ресурсу /cashiers/ можна отримати доступ до списку касирів, а також додати в довідник нові дані.

13.1. Структура об'єкта:

Назва поля Тип поля розмір Обов'язково Тільки читання Примітка
url URL ні так url цього об'єкта
cashier_id рядок 50 так ні повинен бути унікальним та відповідати id одиниць виміру з клієнтської бухгалтерської програми
name рядок 100 так ні ПІП касира

13.2. Доступні команди:

З ресурсом /cashiers/ підтримуються наступні команди:

  • GET - отримати одну сторінку колекції
  • POST - добавити одиницю виміру чи список одиниць виміру у Довідник касирів
  • OPTIONS - мета-інформація по структурі об'єкта
  • HEAD - аналог GET, але повертається тільки заголовок відповіді

13.2.1. GET /cashiers/ - отримати одну сторінку колекції.

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

Суфікси:
  • .json - Отримати відповідь з сервера в форматі JSON
  • .api - Отримати відповідь з сервера в форматі HTML (тестова платформа)
Параметри:
  • format=json|api - аналог вищевказаних суфіксів
  • page_size={nn} - встановити розмір сторінки рівний {nn} об'єктів
  • page={n} - завантажити сторінку {n}
  • search = {substring} - відображати тільки об'єкти, в полі name яких знайдено фрагмент "{substring}"
  • ordering=name|identifier - сортувати по полю в алфавітному порядку (від меншого - до більшого)
  • ordering=-name|-identifier - сортувати по полю в зворотному порядку

ПРИМІТКА: identifier - означає сортування по полю cashier_id

Відповідь з сервера:

Об'єкт "колекція" із чотирьох полів (count,next, previous,results).

Приклад порожньої колекції, отриманої в результаті запиту:

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

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

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

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS

{
"count": 5,
"next": "http://api.datawiz.io/api/v1/cashiers/?page=2&page_size=2",
"previous": null,
"results": [
{
"url": "http://api.datawiz.io/api/v1/cashiers/001/",
"cashier_id": "001",
"name": "Cashier #1"
},
{
"url": "http://api.datawiz.io/api/v1/cashiers/002/",
"cashier_id": "002",
"name": "Cashier #2"
}
]
}
Повідомлення про помилку:

У випадку виникнення помилки сервер повертає відповідь з відповідним статусом, а також повідомленням про помилку, записаним в ключі detail: 

HTTP 404 NOT FOUND 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 

{
"detail": "Not found"
}

13.2.2. POST /cashiers/ - добавити один об'єкт у Довідник касирів.

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

Суфікси:
  • .json - Взаємодіяти з сервером в форматі JSON
  • .api - Взаємодіяти з сервером в форматі HTML (тестова платформа)
Параметри:
  • `format=json - взаємодіяти з сервером в форматі JSON
  • `format=api - взаємодіяти з сервером в форматі HTML (тестова платформа)
Дані запиту:

В запиті передається JSON-об'єкт типу словник (dictionary), який описує новий товар. Важливі всі поля: cashier_id і name. Порядок послідовності полів не принциповий.

Приклад запиту на додавання одного нового об'єкта в Довідник касирів: POST http://api.datawiz.io/api/v1/cashiers/.json 

{
    "cashier_id": "20", 
    "name": "Cashier #20" 
}
Відповідь сервера:

При коректній обробці запиту сервер повертає код статусу 201 і статус створення об'єкта.

Приклад відповіді сервера: 

HTTP 201 CREATED 
Content-Type: application/json 
Vary: Accept 
Location: http://api.datawiz.io/api/v1/cashiers/2/ 
Allow: GET, POST, HEAD, OPTIONS 

{
"updated": 0,
"inserted": 1
}
Умови і обмеження (Constraints):
  • cashier_id уже існує на сервері, то вказаний запит замінить об'єкт на сервері (replace) без попередження.
  • Поле name не може бути порожнім.
Повідомлення про помилку:

У випадку виникнення помилки сервер повертає відповідь з відповідним статусом, а також повідомленням про помилку, записаним навпроти імені поля, з яким ця помилка пов'язана. Якщо помилка стосується не окремого поля, а всього об'єкта, то повідомлення про помилку буде записано навпроти ключа non_field_errors.

ПРИМІТКА. Кожне повідомлення про помилку являє собою колекцію (масив) рядків символів.

Приклад відповіді сервера при виникненні помилки (поле name передано порожнім): 

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
     "name": [
         "This field is required." 
     ] 
}

13.2.3. POST /cashiers/ - пакетне (bulk) додавання об'єктів у Довідник касирів.

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

Суфікси:
  • .json - Взаємодіяти з сервером в форматі JSON
  • .api - Взаємодіяти з сервером в форматі HTML (тестова платформа)
Параметри:
  • `format=json - взаємодіяти з сервером в форматі JSON
  • `format=api - взаємодіяти з сервером в форматі HTML (тестова платформа)
Дані запиту:

В запиті передається JSON-об'єкт типу список (list), який містить один чи більше об'єктів (json-словник(dictionary), див.п.13.2.2), які описують нову одиницю виміру. Передача на сервер об'єктів не по одинці, а списком дозволяє значно збільшити швидкість передачі об'єктів.

Приклад запиту на пакетне додавання трьох нових об'єктів у Довідник касирів: POST http://api.datawiz.io/api/v1/cashiers/.json 


[
    {
        "cashier_id": "001", 
        "name": "Cashier #1"
    },
    {
        "cashier_id": "002", 
        "name": "Cashier #2"
    },
    {
        "cashier_id": "003", 
        "name": "Cashier #1"
    }
]
Відповідь сервера:

При коректній обробці запиту сервер повертає код статусу 201 і статистику по доданих/змінених об'єктах.

Приклад відповіді сервера:

HTTP 201 CREATED
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS

{
"updated": 0,
"inserted": 3
}
Умови і обмеження (Constraints):
  • Якщо об'єкт з ідентифікатором cashier_id уже існує на сервері, то вказаний запит замінить об'єкт на сервері (replace) без попередження.
  • Поле name не може бути порожнім.
Повідомлення про помилку:

У випадку виникнення помилки сервер повертає відповідь з відповідним статусом, а також повідомленням про помилку, записаним в позиції об'єкта, в якому відбулась помилка, навпроти імені поля, з яким ця помилка пов'язана. Якщо помилка стосується не окремого поля, а всього об'єкта, то повідомлення про помилку буде записано навпроти ключа non_field_errors.

ПРИМІТКА. Кожне повідомлення про помилку являє собою колекцію (масив) рядків символів.

Приклад відповіді сервера при виникненні помилки (поле name другого об'єкта не заповнено): 

HTTP 400 BAD REQUEST
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS

[
{},
{
"name": [
"This field is required."
]
},
{}
]

Як бачимо, помилка відбулась у другому об'єкті, в полі name. Тут же вказана і причина помилки.

13.2.4. OPTIONS /cashiers/ - мета-інформація по структурі об'єкта

При виконанні даної команди повертається така JSON-структура:

OPTIONS /api/v1/cashiers/ 

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS

{
"name": "Cashier List",
"description": "this is my Cashier text. You can see this text on the REST-page",
"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
},
"cashier_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 100
}
}
}
}

14. Ресурс cashiers/{id} - визначений об'єкт із Довідника касирів.

Скориставшись ресурсом /cashiers/{id} можна отримати із сервера, модифікувати повністю і частково, а також видалити вибраний об'єкт із Довідника касирів. Для вибору потрібного об'єкта необхідно замінити {id} в URL ресурсу на ідентифікатор із поля cashier_id існуючого об'єкта. Перелік існуючих об'єктів і їх ідентифікаторів можна отримати скориставшись командою 'GET /cashiers/' (детальніше див.розділ "[13. Ресурс /cashiers/ (Довідник касирів, Колекція)]")

14.1. Структура об'єкта:

Назва поля Тип поля розмір Обов'язково Тільки читання ПРИМІТКА
url URL ні так url цього об'єкта
cashier_id рядок 50 так ні повинен бути унікальним та відповідати id одиниць виміру з клієнтської бухгалтерської програми
name рядок 100 так ні ПІП касира

14.2. Доступні команди:

З ресурсом /cashiers/{id} підтримуються наступні команди:

  • GET - отримати об'єкт з cashier_id={id}
  • PUT - повністю замінити об'єкт на сервері новим
  • PATCH - змінити значення окремих полів об'єкта
  • DELETE - вилучити із Довідника касирів об'єкт з cashier_id={id}
  • OPTIONS - мета-інформація по структурі об'єкта
  • HEAD - аналог GET, але повертається тільки заголовок відповіді

14.2.1. GET - отримати об'єкт з cashier_id={id}

Вид команди: GET http://api.datawiz.io/api/v1/cashiers/003 - отримати об'єкт з cashier_id=003

Суфікси:
  • .json - Отримати відповідь з сервера в форматі JSON
  • .api - Отримати відповідь з сервера в форматі HTML (тестова платформа)
Параметри:
  • format=json|api - встановити формат даних. Аналог вищевказаних суфіксів
Відповідь з сервера:

При відправленні на сервер команди GET /cashiers/{id} з порожнім тілом запиту сервер повертає об'єкт заданої структури в форматі JSON чи повідомлення про помилку.

Наприклад, GET http://api.datawiz.io/api/v1/cashiers/003/.json: 

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH

{
"url": "http://api.datawiz.io/api/v1/cashiers/003/",
"cashier_id": "003",
"name": "Cashier #3"
}
Повідомлення про помилку:

У випадку виникнення помилки сервер повертає відповідь з відповідним статусом, а також повідомленням про помилку, записану в ключі detail: 

HTTP 404 NOT FOUND 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 

{
"detail": "Not found"
}

14.2.2. PUT /cashiers/{id}/ - повністю замінити об'єкт на сервері новим.

Фактично даний запит працює, як два послідовних запити: 1 Видалити об'єкт із старим cashier_id = {id} (DELETE) 2 Створити новий об'єкт із новим cashier_id (POST)

Вид команди: PUT http://api.datawiz.io/api/v1/cashiers/003/.json - замінити об'єкт з cashier_id="003" на інший

Суфікси:
  • .json - Взаємодіяти з сервером в форматі JSON
  • .api - Взаємодіяти з сервером в форматі HTML (тестова платформа)
Параметри:
  • format=json - взаємодіяти з сервером в форматі JSON
  • format=api - взаємодіяти з сервером в форматі HTML (тестова платформа)
Дані запиту:

В запиті передається JSON-об'єкт з новим значенням об'єкта

Важливі всі поля: cashier_id і name.

Приклад запиту на заміну об'єкта в Довіднику касирів:

PUT http://api.datawiz.io/api/v1/cashiers/003/.json

{
    "cashier_id": "0034", 
    "name": "Cashier #003 (Another Name)" 
}

Тут під заміну попадає поле name. Зазначимо, що при заміні значення ключового поля (identifier, в даному випадку - cashier_id), дане поле зміниться всюди, і всі зв'язки збережуться.

Відповідь сервера:

При коректній обробці запиту сервер повертає код статусу 200 змінений об'єкт із заповненим полем url.

ПРИМІТКА. Якщо змінювалось поле cashier_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/cashiers/003/",
"cashier_id": "003",
"name": "Cashier #003 (Another Name)"
}
Обмеження (Constraints):
  • Якщо об'єкт з ідентифікатором cashier_id вже існує на сервері, то вказаний запит замінить об'єкт на сервері (replace) без попередження.
  • Поле name не може бути порожнім.
Повідомлення про помилку:

У випадку виникнення помилки сервер повертає відповідь з відповідним статусом, а також повідомленням про помилку, записаним навпроти імені поля, з яким ця помилка пов'язана. Якщо помилка стосується не окремого поля, а всього об'єкта, то повідомлення про помилку буде записано навпроти ключа non_field_errors.

ПРИМІТКА. Кожне повідомлення про помилку являє собою колекцію (масив) рядків символів.

Приклад відповіді сервера при виникненні помилки (поле name передано порожнім): 

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
     "name": [
         "This field is required." 
     ] 
}

14.2.3. PATCH /cashiers/{id}/ - змінити значення окремих полів об'єкта.

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

Вид команди: PATCH http://api.datawiz.io/api/v1/cashiers/5/.json - замінити окремі поля об'єкта з cashier_id=5 на інші

Суфікси:
  • .json - Взаємодіяти з сервером в форматі JSON
  • .api - Взаємодіяти з сервером в форматі HTML (тестова платформа)
Параметри:
  • format=json - взаємодіяти з сервером в форматі JSON
  • format=api - взаємодіяти з сервером в форматі HTML (тестова платформа)
Дані запиту:

В запиті передається JSON-об'єкт з новим значенням окремих полів об'єкта

Важливі всі поля: cashier_id, name, packed, pack_capacity.

Приклад запиту на заміну значення полів name для об'єкта з cashier_id=005 у Довіднику касирів:

PATCH http://api.datawiz.io/api/v1/cashiers/5/.json 

{
    "name": "Cashier #5 (new name)"
}
Відповідь сервера:

При коректній обробці запиту сервер повертає код статусу 200 змінений об'єкт із заповненим полем url.

ПРИМІТКА! Якщо змінювалось поле cashier_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/cashiers/005/",
"cashier_id": "005",
"name": "Cashier #5 (new name)"
}
Обмеження (Constraints):
  • Якщо об'єкт з ідентифікатором cashier_id вже існує на сервері, то вказаний запит замінить об'єкт на сервері (replace) без попередження.
  • Поле name не може бути порожнім.
Повідомлення про помилку:

У випадку виникнення помилки сервер повертає відповідь з відповідним статусом, а також повідомленням про помилку, записаним навпроти імені поля, з яким ця помилка пов'язана. Якщо помилка стосується не окремого поля, а всього об'єкта, то повідомлення про помилку буде записано навпроти ключа non_field_errors.

ПРИМІТКА. Кожне повідомлення про помилку являє собою колекцію (масив) рядків символів.

Приклад відповіді сервера при виникненні помилки (поле name передано порожнім): 

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
     "name": [
         "This field is required." 
     ] 
}

14.2.4. DELETE /cashiers/{id}/ - вилучити із Довідника касирів.

Команда DELETE використовується для видалення вказаного об'єкта із Довідника касирів

Вид команди: DELETE http://api.datawiz.io/api/v1/cashiers/100/ - вилучити об'єкт з cashier_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
Обмеження (Constraints):
  • Не можна видалити запис про касира, який використовується в Чеках
Повідомлення про помилку:

У випадку виникнення помилки сервер повертає відповідь з відповідним статусом, а також повідомленням про помилку, записану в ключі detail: 

HTTP 404 NOT FOUND 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 

{
"detail": "Not found"
}

14.2.5.OPTIONS /cashiers/{id}/ - мета-інформація по структурі об'єкта.

При виконанні даної команди повертається така JSON-структура:

OPTIONS /api/v1/cashiers/100/ 

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH

{
"name": "Cashier Instance",
"description": "this is my Cashier text. You can see this text on the REST-page",
"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
},
"cashier_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 100
}
}
}
}
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️