Rest API Список магазинів - datawizio/pythonAPI GitHub Wiki

Список магазинів - це список назв магазинів мережі клієнта і відповідні до них ідентифікатори. З допомогою ресурсу /shops/ можна отримати доступ "тільки для читання" до списку магазинів. Видаляти магазини через REST API не можна. Якщо необхідно добавити/видалити магазин з сервісу звертайтесь до адміністратора сервісу.

Для управління ресурсом /shops/ підтримуються наступні команди:

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

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

• .json - Отримати відповідь з серверу в форматі JSON
• .api - Отримати відповідь з серверу в форматі HTML (тестова платформа)

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

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

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

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

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

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

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
    "count": 11, 
    "next": "http://api.datawiz.io/api/v1/shops/?page=2&page_size=2&format=api", 
    "previous": null, 
    "results": [
        {
            "url": "http://api.datawiz.io/api/v1/shops/3", 
            "shop_id": "3", 
            "name": "Shop 1"
            "address": "address Shop 1" 
            "longitude": "123"         
            "latitude": "123"
        }, 
        {
            "url": "http://api.datawiz.io/api/v1/shops/2", 
            "shop_id": "2", 
            "name": "Shop 2"
            "address": "address Shop 1" 
            "longitude": "123"         
            "latitude": "123"
        }
    ]
}

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

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

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

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

• format = json | api - аналог вищевказаних суфіксів

Дані запиту:

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

Приклад запиту на додавання одного нового магазину: POST http://api.datawiz.io/api/v1/shops/.json

{
    "shop_id": "124", 
    "name": "Склад на олексадрівській", 
    "address": "Олександрова 5А", 
}

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

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

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

• Якщо об'єкт з ідентифікатором shop_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." 
     ] 
}

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

OPTIONS /api/v1/shops/

HTTP 200 OK 
Content-Type: application/json 
Vary: Accept 
Allow: GET, HEAD, OPTIONS 
{
"name": "Shop List",
"description": "",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
]
}

Скориставшись ресурсом /shops/{id} можна завантажити з серверу об'єкт Shop із Списку магазинів. Для вибору потрібного об'єкта необхідно замінити {id} в URL ресурсу на ідентифікатор із поля shop_id існуючого об'єкта. Перелік наявних об'єктів та їх ідентифікатори можна отримати скориставшись командою GET /shops/ (детальніше див.вище розділ "1. Ресурс /shops/ (Список магазинів, Колекція, Тільки для читання)")

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

• GET - отримати об'єкт з shop_id = {id}
• OPTIONS - мета-інформація по структурі об'єкта
• HEAD - аналог GET, але повертається тільки заголовок відповіді

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

• .json - Отримати відповідь з серверу в форматі JSON
• .api - Отримати відповідь з серверу в форматі HTML (тестова платформа)

• Format = json | api - встановити формат даних. Аналог вищевказаних суфіксів

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

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

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
"url": "http://api.datawiz.io/api/v1/shops/1",
"shop_id": "1",
"name": "Shop 1"
"address": "address Shop 1"
"longitude": "123"

"latitude": "123"
}

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

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

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

OPTIONS /api/v1/shops/1/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
"name": "Shop Detail",
"description": "",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
]
}