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

Список магазинов - это список названий магазинов сети клиента и соответствующие им идентификаторы. С помощью ресурса /shops/ можно получить доступ "только для чтения" к списку магазинов. Удалять магазины через REST API нельзя. При необходимости добавить/удалить магазин из сервиса обращайтесь к администратору сервиса.

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

• GET - получить одну страницу коллекции
• POST - добавить магазин, либо список магазинов
• 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"
]
}