Backend API - kzagorulko/flower-system GitHub Wiki

Взаимодействие клиента и сервера происходит в соответствии с протоколом REST.

В заголовке метода сначала стоит тип запроса (POST, GET, PATCH, DELETE, ...), затем указан путь, по которому нужно совершить запрос.

Например, если указан заголовок GET /users/, то необходимо выполнить GET запрос по адресу /users/

Если первой строкой после заголовка указано TOKEN REQUIRED, то при запросе необходимо отправлять заголовок Authorization: Bearer <access-token>

Если указано REFRESH TOKEN REQUIRED, то в Authorization необходимо класть refresh-token соответственно: Authorization: Bearer <refresh-token>

После заголовка ответа первой строкой указывается для успешного ответа его тип и код Например, Если в ответе указано JSON \ 200, значит в ответе будет указан заголовок Content-type: application/json, код ответа будет 200, а тело ответа будет оформлено в соответствии с JSON

Если на сервере произошла ошибка, то будем возвращен ответ в соответствии со следующим шаблоном:

JSON \ <status_code>

{
    "description": "<детальный текст ошибки>"
}

Переменная status_code равна коду ошибки в соответствии с кодами ответов HTTP

• POST /users/access-tokens - получить access-token
• POST /users/refresh-tokens - получить refresh-token

• GET /users/ - получить список пользователей
• GET /users/{user_id} - получить подробную информацию о пользователях

• GET /providers/ - получить список поставщиков
• GET /providers/{provider_id} - получить подробную информацию о поставщике
• GET /providers/actions - получить полномочия пользователя для работы с поставщиками
• POST /providers/ - создать нового поставщика
• PATCH /providers/{provider_id:int} - обновить данные о поставщике

• GET /branches/ - получить список филиалов
• GET /branches/{branch_id:int} - получить информацию о филиале
• POST /branches/ - создать новый филиал
• PATCH /branches/{branch_id:int} - обновить данные о филиале

• POST /products/ - создать новый продукт
• GET /products/ - получить список продуктов
• PATCH /products/{product_id} - изменить данные о продукте
• GET /products/{product_id} - получить подробную информацию о поставщике

• POST /sales/ - добавить отчет о продаже
• GET /sales/ - получить список отчетов
• GET /sales/{sale_id} - получить подробную информацию о продаже (вместе с информации о продукте и филиале)

• GET /warehouses/ - получить список складов
• GET /warehouses/{warehouse_id} - получить информацию о складе вместе со списком продукции
• POST /warehouses/ - создать новый склад
• PATCH /warehouses/{warehouse_id} - изменить склад

• GET /purchases/ - получить список закупок
• GET /purchases/{purchase_id} - получить информацию о закупке
• POST /purchases/ - создать закупку
• PATCH /purchases/{purchase_id}/status - изменить статус закупки

• GET /supplies/ - получить список поставок
• GET /supplies/{supply_id} - получить информацию о поставке
• POST /supplies/ - создать поставку

• POST /requests/ - создать заявку
• GET /requests/ - получить список заявок
• GET /requests/{request_id} - получить подробную информацию о заявках
• PATCH /requests/{request_id} - стать исполнителем заявки
• PATCH /requests/{request_id}/status - изменить статус заявки

• POST /requests/categories/ - создать категорию заявки
• GET /requests/categories/ - получить категории заявок
• GET /requests/categories/{category_id} - получить категорию заявки
• PATCH /requests/categories/{category_id} - изменить имя категории заявки

Метод для получения refresh-token (действует 30 дней) и access-token (действует 15 минут).

JSON

JSON \ 200

{
    "id": "<user.id>",
    "username": "<user.username>",
    "refresh_token": "<refresh-token>",
    "access_token": "<access-token>",
}

REFRESH TOKEN REQUIRED

Метод для получения access-token (действует 15 минут).

JSON \ 200

{
    "access_token": "<access-token>",
}

TOKEN REQUIRED

Метод для получения пользователей [TODO: с возможностью фильтрации] и пагинации

form-data

JSON \ 200

{
    "items": [
        {
            "id": "<id>",
            "username": "<username>",
        }
    ],
    "total": "<list size>",
}

TOKEN REQUIRED

Метод для получения подробной информации о пользователе

empty

JSON \ 200

{
    "id": 1,
    "displayName": "Администратор",
    "username": "admin",
    "email": "[email protected]",
    "deactivated": false,
    "branches": [
        {
            "id": 1,
            "address": "г. Москва, ул. Улица, д. -1"
        }
    ],
    "role": "Администрация"
}

TOKEN REQUIRED

Возвращает список всех поставщиков с заданными параметрами сортировки

JSON/200

{
   "items":[
      {
         "id":"<id>",
         "name":"<name>",
         "status":"<status>"
      },
   ],
   "total":"<int>"
}

TOKEN REQUIRED

Возвращает полные данные о поставщике

`JSON/200"

{
   "id":"<id>",
   "name":"<name>",
   "status":"<status>",
   "email":"<email>",
   "phone":"<phone>",
   "data":"<data>"
}

TOKEN REQUIRED Возвращает список доступных действий с поставщиками для текущего пользователя

JSON/200

{
   "actions":[
      "get",
      "create",
      "update",
      "update_status"
   ]
}

TOKEN REQUIRED

Метод для создания поставщиков

JSON

JSON/200

{ "id": "<id>" }

TOKEN REQUIRED

Метод для обновления данных о поставщике и/или его статуса.

JSON - те же, что и в методе POST /providers/ + status

No content 204

TOKEN REQUIRED

Возвращает список всех филиалов с заданными параметрами сортировки

JSON/200

{
   "items":[
      {
         "id":"<id>",
         "address":"<address>",
      },
   ],
   "total":"<int>"
}

TOKEN REQUIRED

Возвращает полные данные о филиале

JSON/200

{
   "id":"<id>",
   "address":"<address>",
   "users":[
       {
          "id":"<id>",
          "username": "<username>", 
       }
   ]
}

TOKEN REQUIRED

Метод для создания филиалов

JSON

JSON/200

{ "id": "<id>" }

TOKEN REQUIRED

Метод для обновления данных о филиале.

JSON - те же, что и в методе POST

No content 204

TOKEN REQUIRED

Создать продукт

JSON

JSON / 200

{
   "id": "new product id"
}

TOKEN REQUIRED

Получить список продуктов

JSON

JSON / 200

{
    "items": [{
        "id": "<id>",
        "name": "<name>",
        "price": "<price>",
        "image_path": "<full image path>",
        "description": "<description>"
    }],
    "total": "<amount of all items>"
}

TOKEN REQUIRED

Изменить продукт

JSON

JSON / 200

{
    "product": {
        "id": "<id>",
        "name": "<name>",
        "price": "<price>",
        "image_path": "<full image path>",
        "description": "<description>"
    }
}

TOKEN REQUIRED

Получить информацию о продукте

EMPTY

JSON / 200

{
    "id": "<id>",
    "name": "<name>",
    "price": "<price>",
    "image_path": "<full image path>",
    "description": "<description>"
}

TOKEN REQUIRED

Создать отчет о продаже. Создавать привязанный к филиалу отчет о продаже может только пользователь, состоящий с этом филиале.

Создается раз в месяц для каждого продукта каждым из филиалов.

JSON

JSON / 200

{
   "id": "new sale id"
}

TOKEN REQUIRED

Получить список продуктов

JSON

Параметры year и month следует отправлять вместе. По-одному параметры не будут учитываться.

JSON / 200

[
    {
        "date": "08.2020",
        "sales": [
            {
                "id": "<sale_id>",
                "value": "<value>",
                "product_id": "<product_id>",
                "branch_id": "<branch_id>",
            },
            {"... sale2 info"},
        ]
    },
    {
        "date": "07.2020",
        "sales": [
            {"... sale3 info"},
            {"... sale4 info"},
        ]
    },
]

TOKEN REQUIRED

Получить подробную информацию о продаже.

Ответ включает информацию о продукте и филиале

EMPTY

JSON / 200

{
    "items": {
        "id": 3,
        "value": 9.0,
        "date": "2020.11.13 00:00:00",
        "product_id": 3,
        "branch_id": 2,
        "product": {
            "id": 3,
            "name": "Ромашка",
            "price": 5.0,
            "image_path": "http://127.0.0.1:8000/media/image",
            "description": "Одно из наиболее известных лекарственных растений"
        },
        "branch": {
            "id": 2,
            "address": "г. Москва, ул. Молодогвардейская, д. 61, стр.16"
        }
    }
}

TOKEN REQUIRED

Создать заявку

JSON

JSON / 200

{
   "id": "new request id"
}

TOKEN REQUIRED

Получить список заявок

JSON

JSON / 200

{
    "items": [{
        "id": "<id>",
        "name": "<name>",
        "status": "<Имя статуса (на русском)",
        "statusCode": "<Код статуса>",
        "created": "<created>",
        "hasExecutor": "<есть ли исполнитель>"
    }],
    "total": "<amount of all items>"
}

TOKEN REQUIRED

Назначить себя на заявку

EMPTY

No content / 204

TOKEN REQUIRED

Получить информацию о заявке

EMPTY

JSON / 200

{
    "id": "<id>",
    "name": "<name>",
    "description": "<description>",
    "status": "<Имя статуса (на русском)",
    "statusCode": "<Код статуса>",
    "created": "<created>",
    "hasExecutor": "<есть ли исполнитель>",
    "category": "<Категория заявки>",
    "creator": "<Пользоватль-создатель заявки>",
    "executor": "<Пользователь-исполнитель>"
}

TOKEN REQUIRED

Изменить статус заявки

No content / 204

TOKEN REQUIRED

Создать категорию заявки

JSON

JSON / 200

{
   "id": "new request category id"
}

TOKEN REQUIRED

Получить список категорий заявок

JSON

JSON / 200

{
    "items": [{
        "id": "<id>",
        "name": "<name>"
    }],
    "total": "<amount of all items>"
}

TOKEN REQUIRED

Исправить имя категории

No content / 204

TOKEN REQUIRED

Получить информацию о категории заявки

EMPTY

JSON / 200

{
    "id": "<id>",
    "name": "<name>",
}

TOKEN REQUIRED

Создать склад

JSON

Вместимость, как и все value, измеряется в условных единицах

JSON / 200

{
    "id": "<id>",
}

TOKEN REQUIRED

Получить список складов

form-data

Вместимость, как и все value, измеряется в условных единицах

JSON / 200

{
    "items": [
        {
            "id": 1,
            "address": "г. Москва, ул. Пушкина, д. 30",
            "max_value": 567.0,
            "left_amount": 267.0
        }
    ],
    "total": 1
}

TOKEN REQUIRED

Изменить данные склада

JSON

No content / 204

TOKEN REQUIRED

Получить инфо о складе вместе с продуктами

EMPTY

JSON / 200

{
    "id": 1,
    "address": "г. Москва, ул. Пушкина, д. 30",
    "max_value": 567.0,
    "left_amount": 267.0,
    "products": [
        {
            "id": 2,
            "value": 300.0
        }
    ]
}

TOKEN REQUIRED

Создать закупку

JSON

Величина закупки, как и все value, измеряется в условных единицах

JSON / 200

{
    "id": "<id>",
}

TOKEN REQUIRED

Изменить статус закупки

При изменении статуса закупки на DONE, продукт автоматически привязывается к складу

JSON

Статус NEW устанавливается при создании

No content / 200

TOKEN REQUIRED

Получить список закупок

form-data

JSON / 200

{
    "items": [
        {
            "id": 1,
            "value": 100.0,
            "status": "Новая",
            "product_id": 1,
            "warehouse_id": 1
        }
    ],
    "total": 1
}

TOKEN REQUIRED

Получить инфо о закупке

EMPTY

JSON / 200

{
    "id": 1,
    "value": 100.0,
    "status": "Новая",
    "product_id": 1,
    "warehouse_id": 1
}

TOKEN REQUIRED

Создать поставку

JSON

Величина поставки, как и все value, измеряется в условных единицах

JSON / 200

{
    "id": "<id>",
}

TOKEN REQUIRED

Получить список поставок

form-data

JSON / 200

{
    "items": [
        {
            "id": 1,
            "value": 100.0,
            "product_id": 1,
            "warehouse_id": 1,
            "branch_id": 1
        }
    ],
    "total": 1
}

TOKEN REQUIRED

Получить инфо о поставке

EMPTY

JSON / 200

{
    "id": 1,
    "value": 100.0,
    "product_id": 1,
    "warehouse_id": 1,
    "branch_id": 1
}