API таро

За необов'язковим запитанням і необов'язковим seed ендпоінт витягує карти з повної 78-карткової колоди для розкладу на три карти, причому кожна карта потрапляє у визначену позицію та орієнтується прямо чи перевернуто. Відповідь описує сам розклад, повертає використаний цілочисловий seed і перелічує витягнуті карти — кожна несе мітку позиції, свою орієнтацію та значення, прив'язане до цієї карти в цій орієнтації. Seed — серце цієї конструкції: пропустіть його, і сервер згенерує його за вас і поверне; передайте його, і ви відтворите ідентичний розклад, що робить трактування придатними до поширення, тестування й аудиту. Прапорець allowReversed визначає, чи взагалі можливі перевертання. Інші розклади — на одну карту, Кельтський хрест, підкова, на стосунки та на рік уперед — є спорідненими ендпоінтами на тій самій колоді та механізмі засівання.

curl -X POST https://api.astroway.info/v1/tarot/rider-waite/draw/three-card \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "question": "How will my new project unfold?"
}'

{
  "ok": true,
  "data": {
    "spread": {
      "slug": "three-card",
      "name": "Three Card",
      "cardCount": 3
    },
    "seed": 4044793529,
    "drawn": [
      {
        "position": {
          "index": 0,
          "name": "Past"
        },
        "card": {
          "slug": "knight-of-wands",
          "name": "Knight of Wands"
        },
        "reversed": false,
        "meaning": "…"
      }
    ]
  }
}

Звертайтеся до нього, коли хочете трактування таро, яке можна відтворити на вимогу, а не одноразовий випадковий розклад. Збережіть повернутий seed — і ви зможете перерендерити ті самі три карти згодом: у спільному посиланні, збереженому трактуванні, регресійному тесті чи зверненні підтримки — не зберігаючи перелік карт самотужки. Використовуйте фіксований seed у тестах, щоб ваш інтерфейс і текст рендерилися детерміновано, а в продакшені дозволяйте серверу карбувати свіжий seed заради справжнього розмаїття. Беріть саме розклад на три карти, коли потрібна компактна структура на кшталт минуле/теперішнє/майбутнє; перемикайтеся на споріднений ендпоінт, коли досвіду краще пасує розкладка з більшою кількістю позицій.

Зображення карт — колода Райдера-Вейта-Сміт (А. Е. Вейт і Памела Колман Сміт, 1909), що перебуває в суспільному надбанні. Установіть allowReversed у false, щоб витягати лише прямі карти — корисно для трактувань, дружніх до новачків, де перевернуті значення лише додавали б плутанини. Той самий seed відтворює розклад тільки для того самого розкладу й того самого значення allowReversed.