Глосарій

Кінцева точка

https://api.white.market/graphql/partner

Запит

Запит можна надіслати через HTTP POST.

Стандартний POST-запит GraphQL має використовувати тип вмісту application/json і включати тіло в кодуванні JSON такої форми:

{
  "query": "...",
  "operationName": "...",
  "variables": { "myVariable": "someValue", ... }
}

operationName та variables є необов’язковими полями.

operationName потрібен, лише якщо в запиті присутні кілька операцій.

Відповідь

Незалежно від методу, за допомогою якого було надіслано запит і змінні, відповідь має бути повернута в тілі запиту у форматі JSON. Як зазначено в специфікації, запит може призвести до деяких даних і деяких помилок, і вони повинні повертатися в об’єкті JSON у формі:

{
  "data": { ... },
  "errors": [ ... ]
}

Якщо помилок не було повернуто, поле “errors” не повинно бути у відповіді. Якщо дані не повертаються, відповідно до специфікації GraphQL, поле «data» слід включати, лише якщо під час виконання не сталося жодних помилок.

Помилки

Помилки HTTP

Кінцева точка GraphQL може повертати наступні коди HTTP:

• 200 - тіло містить відповідь про успіх або помилку GraphQL;
• 400 - неправильний запит JSON, поганий синтаксис GraphQL, більше ніж 1 мутація в 1 запиті;
• 401 - неправильний або прострочений токен JWT у заголовку автентифікації;
• 429 - занадто багато однакових мутацій одночасно, надсилайте запити повільніше та окремо;
• 503 - повторить спробу через деякий час, описаний у Retry-After.

Помилка повинна містити:

• message - опис помилки, зрозумілий людині;
• extension.category - мнемонічне незмінне ім’я помилки.

Example:

{
  "errors": [
    {
      "message": "❗️ Oops! Item not found.",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "market_item"
      ],
      "extensions": {
        "category": "market.product.not_found"
      }
    }
  ]
}

Query

Операція GraphQL може бути операцією читання або запису.

Запит GraphQL використовується для читання або отримання значень. У будь-якому випадку операція є простим рядком, який сервер GraphQL може проаналізувати та відповісти даними в певному форматі. Популярним форматом відповіді, який зазвичай використовується для мобільних і веб-додатків, є JSON.

Приклад:

#запит з назвою myQuery
query myQuery{
    greeting
}

#запит без імені
{
    greeting
}

Mutation

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

Мутація GraphQL використовується для запису чи публікації значень.

Синтаксис наведено нижче:

mutation{
   someEditOperation(dataField:"valueOfField"):returnType
}

Пагінація на основі курсора

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

Плюси та мінуси

Переваги

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

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

Недоліки

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

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

Enum

Enum (скорочення від «enumeration») у GraphQL представляє кінцевий набір попередньо визначених значень.

Це дозволяє визначити конкретний список дійсних параметрів для поля. Переліки корисні, коли поле може мати лише обмежену кількість певних значень.

Наприклад, ви можете визначити тип переліку для можливих статусів завдання, як-от “COMPLETED,” “IN_PROGRESS,” or “CANCELLED”.

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

Type

Тип у GraphQL визначає складну структуру даних з одним або кількома полями. Типи використовуються для опису форми об’єктів даних, які повертає API. Вони можуть мати кілька полів різних типів, що дозволяє представляти та організовувати складні зв’язки даних.

Типами можуть бути об’єкти, інтерфейси або об’єднання. Типи об’єктів представляють певну сутність із власним набором властивостей і поведінки.

Інтерфейси визначають загальний набір полів, які можуть реалізувати кілька типів об’єктів.

Об’єднання представляють тип, який може бути одним із кількох можливих типів об’єктів.

Резюме

Таким чином, Enum використовуються для визначення певного набору дозволених значень для поля, тоді як Type використовуються для визначення загальної структури та зв’язків об’єктів даних у GraphQL. Enum надають спосіб обмежити можливі значення, забезпечуючи узгодженість даних і запобігаючи помилкам, тоді як типи дозволяють гнучке та складне моделювання даних.