Rest API Справочник категорий товаров - datawizio/pythonAPI GitHub Wiki

Справочник категорий товаров - это иерархический (древовидный) список категорий товаров. С помощью ресурса /categories/ можно получить доступ к списку категорий товаров, а также добавлять в справочник новые категории и удалять ненужные.

С ресурсом /categories/ поддерживаются следующие команды:

• GET - получить одну страницу коллекции
• POST - добавить новую категорию товара либо список категорий в Справочник категорий товаров
• OPTIONS - мета-информация по структуре объекта
• HEAD - аналог GET, но возвращается только заголовок ответа

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

• .json - Получить ответ с сервера в формате JSON
• .api - Получить ответ с сервера в формате HTML (тестовая площадка)

• format=json|api - аналог вышеуказанных суффиксов
• page_size={nn} - установить размер страницы равный {nn} объектов
• page={n} - скачать страницу {n}
• parent_id={n} - отображать только категории, принадлежащие родительской категории с category id={n}
• search = {substring} - отображать только объекты, в поле name которых найдено фрагмент "{substring}"
• ordering=name - сортировать по полю в алфавитном порядке (от меньшего - к большему)
• ordering=-name - сортировать по полю в обратном порядке

Объект "коллекция" состоит из четырех полей (count,next, previous,results).

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

GET http://api.datawiz.io/api/v1/categories/.json/?search=unknown-name

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

Пример коллекции из 2-х элементов, полученных по запросу: "вернуть всех 'детей' указанной категории": GET http://api.datawiz.io/api/v1/categories/?parent_id=2:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"url": "http://api.datawiz.io/api/v1/categories/3/",
"category_id": "3",
"name": "cat1",
"parent_id": "2",
"parent_url": "http://api.datawiz.io/api/v1/categories/2/"
},
{
"url": "http://api.datawiz.io/api/v1/categories/4/",
"category_id": "4",
"name": "cat2",
"parent_id": "2",
"parent_url": "http://api.datawiz.io/api/v1/categories/2/"
}
]
}

В случае возникновения ошибки сервер возвращает ответ с соответствующим статусом, а также сообщением об ошибке, записаннoe в ключе 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/categories/?format=json

• .json - Взаимодействовать с сервером в формате JSON
• .api - Взаимодействовать с сервером в формате HTML (тестовая площадка)

• format=json - взаимодействовать с сервером в формате JSON
• format=api - взаимодействовать с сервером в формате HTML (тестовая площадка)

В запросе передается JSON-объект типа словарь (dictionary), который описывает новую категорию. Важны все поля: category_id, parent_id и name. Поле parent_id может принимать значение null, если категория не имеет родителя (категория верхнего уровня). Порядок следования полей не принципиален.

Пример запроса на добавление одного нового объекта в Справочник категорий товаров: POST http://api.datawiz.io/api/v1/categories/.json

{
    "category_id": "124", 
    "name": "Хлебо-булочные изделия", 
    "parent_id": "2", 
}

При корректной обработке запроса сервер возвращает код статуса 201 и статус создания обьекта.

Пример ответа сервера:

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

• Если объект с идентификатором category_id уже существует на сервере, то указанный запрос заменит объект на сервере (replace) без предупреждения.
• Нельзя добавить на сервер объект, если не существует родительской категории с указанным идентификатором parent_id
• Поле 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." 
     ] 
}

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

• .json - Взаимодействовать с сервером в формате JSON
• .api - Взаимодействовать с сервером в формате HTML (тестовая площадка)

• `format=json - взаимодействовать с сервером в формате JSON
• `format=api - взаимодействовать с сервером в формате HTML (тестовая площадка)

В запросе передается JSON-объект типа список (list), который содержит один или более объект, описывающий новую категорию. Передача на сервер объектов не по одиночке, а списком позволяет значительно увеличить скорость передачи данных.

Пример запроса на пакетное добавление трёх новых объектов в Справочник категорий товаров: POST http://api.datawiz.io/api/v1/categories/.json

[
    {
        "category_id": "124", 
        "name": "Хлебо-булочные изделия", 
        "parent_id": "2" 
    },
    {
        "category_id": "125", 
        "name": "Молочные продукты", 
        "parent_id": "2" 
    },
    {
        "category_id": "126", 
        "name": "Кулинария", 
        "parent_id": "2" 
    }
]

При корректной обработке запроса сервер возвращает код статуса 201 и статистику по добавленным/изменённым объектам.

Пример ответа сервера:

HTTP 201 CREATED
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"updated": 1,
"inserted": 2
}

• Если объект с идентификатором category_id уже существует на сервере, то указанный запрос заменит объект на сервере (replace) без предупреждения.
• Нельзя добавить на сервер объект, если УЖЕ не существует родительской категории с указанным идентификатором parent_id
• Поле name не может быть пустым.

В случае возникновения ошибки сервер возвращает ответ с соответствующим статусом, а также сообщениями об ошибке, записанными в позиции объекта, в котором произошла ошибка, напротив имени поля, с которым эта ошибка связана. Если же ошибка касается не отдельного поля, а всего объекта, то сообщение об ошибке будет записано напротив ключа non_field_errors.

ПРИМЕЧАНИЕ. Каждое сообщение об ошибке представляет собой коллекцию (массив) символьных строк.

Пример ответа сервера при возникновении ошибки (поле parent_id первого объекта передано неверным):

HTTP 400 BAD REQUEST
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
[
{
"parent_id": [
"Parent category with id=122 does not exist"
]
},
{}
]

Как видно, ошибка произошла в первом объекте, в поле parent_id. Тут же указана и причина ошибки.

При выполнении данной команды возвращается такая JSON-структура:

OPTIONS /api/v1/categories/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"name": "Category List",
"description": "Categories",
"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
},
"category_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 100
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 200
},
"parent_id": {
"type": "string",
"required": false,
"read_only": false,
"max_length": 100
},
"parent_url": {
"type": "field",
"required": false,
"read_only": true
}
}
}
}

Воспользовавшись ресурсом /categories/{id} можно получить с сервера, модифицировать полностью и частично, а также удалить выбранный объект из Справочника категорий товаров. Для выбора нужного объекта необходимо заменить {id} в URL ресурса на идентификатор из поля category_id существующего объекта. Перечень существующих объектов и их идентификаторов можно получить воспользовавшись командой 'GET /categories/' (подробнее см.раздел "[5. Ресурс /categories/ (Справочник категорий товаров, Коллекция)]")

С ресурсом /categories/{id} поддерживаются следующие команды:

• GET - получить объект с category_id={id}
• PUT - полностью заменить объект на сервере новым
• PATCH - изменить значение отдельных полей объекта
• DELETE - изъять из Справочника категорий товаров объект с category_id={id}
• OPTIONS - мета-информация по структуре объекта
• HEAD - аналог GET, но возвращается только заголовок ответа

Вид команды: GET http://api.datawiz.io/api/v1/categories/1-1 - получить объект с category_id="1-1"

• .json - Получить ответ с сервра в формате JSON
• .api - Получить ответ с сервра в формате HTML (тестовая площадка)

• format=json|api - установить формат данных. Аналог вышеуказанных суффиксов

При отправке на сервер команды GET /categories/{id} с пустым телом запроса сервер возвращает объект заданной структуры в формате JSON или сообщение об ошибке.

Например, GET http://api.datawiz.io/api/v1/categories/126/.json:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"url": "http://api.datawiz.io/api/v1/categories/126/",
"category_id": "126",
"name": "Кулинария",
"parent_id": "2",
"parent_url": "http://api.datawiz.io/api/v1/categories/2/"
}

В случае возникновения ошибки сервер возвращает ответ с соответствующим статусом, а также сообщением об ошибке, записанным в ключе detail:

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

Фактически данный запрос работает, как два последовательных запроса: 1 Удалить объект со старым category_id = {id} (DELETE) 2 Создать новый объект с новым category_id (POST)

Вид команды: PUT http://api.datawiz.io/api/v1/categories/126/.json - заменить объект с category_id="126" на другой

• .json - Взаимодействовать с сервером в формате JSON
• .api - Взаимодействовать с сервером в формате HTML (тестовая площадка)

• format=json - взаимодействовать с сервером в формате JSON
• format=api - взаимодействовать с сервером в формате HTML (тестовая площадка)

В запросе передается JSON-объект с новым значением объекта

Важны все три поля: category_id, parent_id и name. Поле parent_id может принимать значение null, если категория не имеет родителя (категория верхнего уровня). Порядок следования полей не принципиален.

Пример запроса на замену объекта в Списке кассовых терминалов:

PUT http://api.datawiz.io/api/v1/categories/126/.json

{
     "category_id": "126", 
     "name": "Кулинария (новая)",
     "parent_id": "3"
}

Здесь замене подлежат поля parent_id и name. Нужно заметить, что при замене значения ключевого поля (identifier, в данном случае - category_id), данное поле изменяется везде, и все связи сохраняются.

При корректной обработке запроса сервер возвращает код статуса 200 и статус создания обьекта.

Пример ответа сервера:

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

• Если объект с идентификатором category_id уже существует на сервере, то указанный запрос заменит объект на сервере (replace) без предупреждения.
• Нельзя добавить на сервер объект, если УЖЕ не существует родительской категории с указанным идентификатором parent_id
• Поле 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." 
     ] 
}

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

Вид команды: PATCH http://api.datawiz.io/api/v1/categories/1-100/.json - заменить отдельные поля объекта с category_id=1-100 на другие

• .json - Взаимодействовать с сервером в формате JSON
• .api - Взаимодействовать с сервером в формате HTML (тестовая площадка)

• format=json - взаимодействовать с сервером в формате JSON
• format=api - взаимодействовать с сервером в формате HTML (тестовая площадка)

В запросе передается JSON-объект с новым значением отдельных полей объекта

Важны все три поля: category_id, shop_id и name.

Пример запроса на замену значения поля name для объекта с category_id=100 в Справочнике категорий товаров:

PATCH http://api.datawiz.io/api/v1/categories/100/.json

{
     "name": "category #100" 
}

При корректной обработке запроса сервер возвращает код статуса 200 и измененный объект с заполненным полем url.

ПРИМЕЧАНИЕ! Если менялось поле category_id, то и поле url также изменится!

Пример ответа сервера:

HTTP 200 OK 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
"url": "http://api.datawiz.io/api/v1/categories/100/",
"category_id": "100",
"name": "category #100",
"parent_id": "3",
"parent_url": "http://api.datawiz.io/api/v1/categories/3/"
}

• Если объект с идентификатором category_id уже существует на сервере, то указанный запрос заменит объект на сервере (replace) без предупреждения.
• Нельзя добавить на сервер объект, если УЖЕ не существует родительской категории с указанным идентификатором parent_id
• Поле 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." 
     ] 
}

Команда DELETE используется для извлечения указанного объекта из Справочника категорий товаров

Вид команды: DELETE http://api.datawiz.io/api/v1/categories/100/ - изъять обьект с category_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/categories/100/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"name": "Category Instance",
"description": "Categories",
"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
},
"category_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 100
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 200
},
"parent_id": {
"type": "string",
"required": false,
"read_only": false,
"max_length": 100
},
"parent_url": {
"type": "field",
"required": false,
"read_only": true
}
}
}
}