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

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

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

25.1.1. Структура объекта Sale:

Название поля Тип поля размер Обязательное Только чтение Примечание
url URL нет да url этого объекта
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"
            ],
            "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"
            ],
            "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"],
    "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
},
"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"
}
}
}
}
}
}
}
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️