Rest API Список акцій - datawizio/pythonAPI GitHub Wiki

25. Ресурс `/sale/` (Список акцій, Колекція)

Список акцій - це список акцій, які відбувались чи відбуваються у магазинах мережі клієнта. З допомогою ресурсу /sale/ можна отримати доступ "тільки для читання" до списку акцій.

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

Назва поля	Тип поля	розмір	Обов'язкове	Тільки читання	Примітка
`url`	URL		ні	так	url цього об'єкта
`sale_id`	рядок	200	так	ні	ідентифікатор акції
`shops`	список		так	ні	магазин або магазини, де діє чи діяла акція
`name`	рядок	100	так	ні	назва акції
`description`	рядок		так	ні	опис акції
`date_from`	дата		так	ні	дата початку дії акції
`date_to`	дата		так	ні	дата завершення дії акції
`products`	список		так	ні	товари, які входять в акцію

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

Назва поля	Тип поля	Обов'язкове	Тільки читання	Примітка
`url`	URL	ні	так	url цього об'єкта
`product_id`	рядок	так	ні	товар
`product_url`	URL	ні	так	url цього об'єкта

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

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

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

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

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

Суфікси:

.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/sale/.json/?search=unknown-string

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

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

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
    "count": 3, 
    "next": "http://api.datawiz.io/api/v1/sale/?page=2&page_size=2&format=api", 
    "previous": null, 
    "results": [
         {
            "url": "http://api.datawiz.io/api/v1/sale/SALE-ID-G10Y-P0T0-X5L9/",
            "shops": [
                "1ca1a667-c335-11e5-b11b-000c29883704",
                "16aa5faa-26e0-11e5-9d5b-000c29883704",
                "0f9e8ac0-3cd5-11e5-9d5b-000c29883704",
                "6d153e30-5076-11e5-ab16-000c29883704",
                "e6491ef8-5709-11e5-ab16-000c29883704",
                "dd582d89-8889-11e5-a127-000c29883704",
                "9856d0f5-0929-11e5-80d8-7054d2c57800"
            ],
            "sale_id": "SALE-1",
            "name": "Тестова",
            "description": "",
            "date_from": "2016-02-22",
            "date_to": "2016-03-10",
            "products": []
        },
        {
            "url": "http://api.datawiz.io/api/v1/sale/SALE-ID-ALFK-NLKS-EG9G/",
            "shops": [
                "6d153e30-5076-11e5-ab16-000c29883704",
                "0f9e8ac0-3cd5-11e5-9d5b-000c29883704",
                "e6491ef8-5709-11e5-ab16-000c29883704",
                "16aa5faa-26e0-11e5-9d5b-000c29883704",
                "dd582d89-8889-11e5-a127-000c29883704",
                "1ca1a667-c335-11e5-b11b-000c29883704",
                "9856d0f5-0929-11e5-80d8-7054d2c57800"
            ],
            "sale_id": "SALE-2",
            "name": "datawiz.io",
            "description": "gfdgdf",
            "date_from": "2016-02-01",
            "date_to": "2016-03-09",
            "products": [
                {
                    "url": "http://api.datawiz.io/api/v1/sale/SALE-ID-ALFK-NLKS-EG9G/products/c9e89a8e-1cd9-11e5-b5eb-000c29883704/",
                    "product_id": "c9e89a8e-1cd9-11e5-b5eb-000c29883704",
                    "product_url": "http://api.datawiz.io/api/v1/product/c9e89a8e-1cd9-11e5-b5eb-000c29883704/"
                },
                {
                    "url": "http://api.datawiz.io/api/v1/sale/SALE-ID-ALFK-NLKS-EG9G/products/d840c496-2195-11e5-8f96-000c29883704/",
                    "product_id": "d840c496-2195-11e5-8f96-000c29883704",
                    "product_url": "http://api.datawiz.io/api/v1/product/d840c496-2195-11e5-8f96-000c29883704/"
                }
    ]
}

Повідомлення про помилку:

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

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

25.2.2 `POST /sale/` - додати одну чи декілька акцій

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

Суфікси:

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

Параметри:

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

Дані запиту:

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

Приклад запиту на додавання однієї нової акції: POST http://api.datawiz.io/api/v1/sale/.json

{
    "shops": ["Shop1", "Shop2"],
    "sale_id": "SALE_1",
    "name": "Молоко", 
    "description": "Акція_по_молоку", 
    "date_from": "2-02-2015", 
    "date_to": "2-03-2015", 
    "products": ["Молоко_козацьке"], 
}

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

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

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

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

Умови та обмеження (Constraints):

Поле 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." 
     ] 
}

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

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

OPTIONS /api/v1/sale/

HTTP 200 OK 
Content-Type: application/json 
Vary: Accept 
Allow: GET, HEAD, OPTIONS 
{
"name": "Sale List",
"description": "",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
],
"actions": {
"POST": {
"url": {
"type": "string",
"required": false,
"read_only": true,
"label": "Url"
},
"shops": {
"type": "list",
"required": true,
"read_only": false,
"label": "Shops",
"child": {
"type": "string",
"required": true,
"read_only": false
}
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "Name",
"max_length": 100
},
"sale_id": {
"type": "string",
"required": true,
"read_only": false,
"label": "Sale id",
"max_length": 200
},
"description": {
"type": "string",
"required": true,
"read_only": false,
"label": "Description"
},
"date_from": {
"type": "date",
"required": true,
"read_only": false,
"label": "Date from"
},
"date_to": {
"type": "date",
"required": true,
"read_only": false,
"label": "Date to"
},
"products": {
"type": "field",
"required": true,
"read_only": false,
"label": "Products",
"child": {
"type": "nested object",
"required": true,
"read_only": false,
"children": {
"url": {
"type": "field",
"required": false,
"read_only": true,
"label": "Url"
},
"product_id": {
"type": "integer",
"required": true,
"read_only": false,
"label": "Product id"
},
"product_url": {
"type": "integer",
"required": false,
"read_only": true,
"label": "Product url"
}
}
}
}
}
}
}

Rest API Список акцій - datawizio/pythonAPI GitHub Wiki

25. Ресурс /sale/ (Список акцій, Колекція)

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

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

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

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

Суфікси:

Параметри:

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

Повідомлення про помилку:

25.2.2 POST /sale/ - додати одну чи декілька акцій

Суфікси:

Параметри:

Дані запиту:

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

Умови та обмеження (Constraints):

Повідомлення про помилку:

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

⚠️ **GitHub.com Fallback** ⚠️

25. Ресурс `/sale/` (Список акцій, Колекція)

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

25.2.2 `POST /sale/` - додати одну чи декілька акцій

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

⚠️ GitHub.com Fallback ⚠️