Механізм пулів у Edibox

У сервісі Edibox пул (анг. pool) - це сховище для довільної інформації, куди компанія може поміщати будь-які дані у різних форматах.

Пул - це нестандартизована інформація у довільному вигляді, якою повністю керує компанія-власник: створює, поновлює, видаляє та надає посилання на цей пул іншим компаніям, яким він потрібен.
Пул може бути у будь-якому з дозволених форматів: json, xml, csv, text та ін. Пул не підпорядковується жодному стандарту або формату - тому компанія сама вирішує, в якому вигляді його буде створено.

Щоб отримати доступ до пулу потрібно знати його ідентифікатор та бути зареєстрованим у сервісі Edibox. Приклад адреси пула: https://edibox.com.ua/api/v1/pools/018e9529-f276-7fd9-b77d-41c44a1e7d03

Детальний опис API Edibox для роботи з пулами можна переглянути на сторінці Edibox OpenApi .

Для чого потрібні пули?

Часто компанії стикаються з тим, що деяка інформація для обміну з партнерами не є предметом стандартизації для обміну електронними документами та повідомленнями. А отже, у провайдерів відсутня можливість передавати таку інформацію взагалі.

Наприклад, постачальник хоче поділитися зі всіма своїми партнерами списком товарів, які беруть участь у маркетинговій програмі або ж мережа магазинів бажає поділитися переліком роздрібних точок, їхніх адрес, годин роботи тощо.

Кожного разу цю інформацію доводиться якось передавати кожному з постачальників через електронну пошту у вигляді документів, excel файлів тощо.
Або ж домовлятися з провайдерами про розробку спеціального формату повідомлення саме під конкретний тип даних, якщо це взагалі можливо.

Механізм пулів створено саме для того, щоб зарадити у цій ситуації.

Робота з пулами

Загальний принцип

Спочатку потрібно створити пустий пул.
Сервіс повертає унікальний ідентифікатор нового пулу.
Далі у пул необхідно записати дані, якими компанія хоче поділитися з іншими зареєстрованими компаніями.
Поділитися посиланням на пул з партнерами, кому це потрібно.
У будь-який момент власник пула може змінити дані пула.
У разі необхідності постачальник може повністю видалити пул з сервісу Edibox.

Створення пулу

Спочатку потрібно створити пул, вказавши його ім’я:
POST /api/v1/pools HTTP/1.1

Тіло запита для створення

{ "name": "Перелік доступних вантажівок" }

Під час цього запиту сервіс Edibox створить новий порожній пул з вказаним іменем та поверне його ідентифікатор для подальшого використання:

{ "uuid": "018e9529-f276-7cfd-97c8-45d2f727bd70" }

Після цього власнику необхідно поновити вміст/дані (content) створеного пула.

Поновлення даних пула

Для поновлення пула необхідно знати його унікальний ідентифікатор, а також бути власником цього пула.
Спроба поновити дані пула не власником призведе до помилки.

PUT

Найлегший спосіб поновити вміст пула - використання методу PUT:
PUT /api/v1/pools/018e9529-f276-7cfd-97c8-45d2f727bd70 HTTP/1.1

В тілі повідомлення передається безпосередній вміст пула, наприклад, json об’єкт з якимись даними.
У запиті також потрібно вказати правильний Content-Type заголовок (header), оскільки надалі саме він буде повертатися у відповіді на отримання вмісту цього пула.

Наприклад, в тілі можна переда об’єкт json, а в Content-Type вказати application/csv - це не призведе до помилки. Однак у сторони, яка потім отримуватиме вміст цього пула, через таку невідповідність можуть виникнути проблеми з автоматичною обробкою цих даних.

Сервіс Edibox підтримує лише обмежений, однак достатній, перелік допустимих content-type для вмісту пола. Найпоширеніші з них:

application/json
application/xml
text/plain
text/csv
text/csv; header=present
…

Для отримання повного переліку, потрібно звернутися до специфікації API: Edibox OpenApi

Приклад поновлення в пулі переліку товарів у вигляді CSV з заголовком.

PUT /api/v1/pools/018e9529-f276-7cfd-97c8-45d2f727bd70 HTTP/1.1
Content-Type: text/csv; header=present
Authorization: Bearer edi:1234567

name,price
Товар 1,200.35
Товар 2,200.35
Товар 3,200.35

PATCH

Дані в пулі можна змінювати використовуючи запит Json Patch (RFC-6902), про який більш детально написано на відповідній сторінці документації.

Список доступних для поновлення полів пула можна прочитати на сторінці специфікації Edibox OpenApi

Наприклад, через PATCH можна виконати поновлення найменування:
PATCH /api/v1/pools/018e9529-f276-7cfd-97c8-45d2f727bd70 HTTP/1.1

Тіло запиту Json Patch для зміни найменування

[
  {
    "operation": "add",
    "path": "/name",
    "value": "Список вільних вантажівок 3т"
  }
]

Також цим же методом можна виконати поновлення вмісту пулу та його content-type:

Тіло запиту Json Patch для поновлення content та content-type

[
  {
    "operation": "add",
    "path": "/content",
    "value": "...."
  },
  {
    "operation": "add",
    "path": "/content-type",
    "value": "text/csv; header=present"
  }
]

Для поновлення вмісту пула можна використати методи PUT або PATCH - за вибором власника. Однак для звичайного поновлення тільки вмісту пула зручніше використовувати метод PUT.

Отримання даних пула

Вміст пулу можна отримати лише знаючи його унікальний ідентифікатор, наприклад,

GET /api/v1/pools/018e9529-f276-7cfd-97c8-45d2f727bd70 HTTP/1.1

У тілі відповіді буде міститися вміст (content) пулу, який було створено його власником. Відповідь обов’язково повертає заголовок (header) Last-Modified, де вказується дата останньої модифікації, а також заголовок (header) Content-Type з вказанням типу даних цього пула.

Content-Type: application/json
Last-Modified: Fri, 03 May 2024 04:10:09 GMT

Отримання об’єкта пула

Також можна отримати об’єкт пула, який міститиме безпосередньо вміст (content) пула та додаткові поля: найменування, власник тощо.

GET /api/v1/pools/018e9529-f276-7cfd-97c8-45d2f727bd70/object HTTP/1.1

Приклад відповіді

{
    "uuid": "018e9529-f276-7cfd-97c8-45d2f727bd70",
    "name": "Перелік доступних вантажівок",
    "owner": {
        "uuid": "10bb41d9-96a2-4517-a13c-2893302e956f",
        "name": "ТзОВ 'Перша логістична компанія'",
        "gln": "9520000000001"
    },
    "content": "[....]",
    "content-type": "application/json",
    "modified_date": "2024-04-24T07:10:09+03:00"
}

Наведена відповідь не містить вичерпного переліку полів об’єкта. Повний перелік полів можна отримати на сторінці опису API Edibox OpenApi