Як працювати з колекцією Postman

Усі запити в колекції потребують автентифікації, тож без ключа дані не повернуться. Створити ключ можна безкоштовно; кредити списуються лише за успішні виклики.

1. 1Зареєструйтеся на occultapi.com/signup і підтвердьте електронну пошту.
2. 2У кабінеті відкрийте API keys і натисніть Create key.
3. 3Одразу скопіюйте ключ. Він показується лише раз і зберігається як хеш, тож ніхто — навіть ми — не покаже його вам удруге. Загубите — доведеться створити новий, відновити не вийде.

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

Запити згруповано так само, як у довіднику: Panchang, Muhurta, Dashas, Charts, Calendars тощо. У кожного той самий опис, що й у документації, і те саме тіло, з яким записано приклад відповіді.

Читати колекцію можна без акаунта, а от надсилати запити — лише з власної копії. Форк її й створює.

1. 1Увійдіть у Postman або створіть безкоштовний акаунт.
2. 2Натисніть Fork Collection угорі колекції або значок форку біля її назви.
3. 3Підпишіть форк — можна просто своїм ім’ям — і виберіть робочий простір для нього.
4. 4Залиште позначку Watch original collection. Завдяки їй ви зможете згодом підтягувати нові ендпоінти, а не робити форк заново.
5. 5Натисніть Fork Collection. Відкриється ваша копія, і ніякі зміни в ній не вплинуть на нашу.

Не хочете заводити акаунт Postman? Завантажте JSON і скористайтеся Import у десктопному Postman. Щоправда, тоді зв’язку з оригіналом не буде, і коли в API з’являться нові ендпоінти, колекцію доведеться імпортувати знову.

Відкрийте вкладку Variables колекції. Там дві змінні: baseUrl, уже заповнена значенням https://api.occultapi.com, і порожня apiKey. Вставте ключ у значення apiKey і збережіть.

Більше нічого для автентифікації робити не треба. Кожен запит колекції бере ключ звідси й надсилає його в заголовку X-API-Key, тож ви задаєте ключ один раз, а не в 299 запитах. Ключа ще немає? Отримайте його в кабінеті.

Кожен запит — це POST із JSON-тілом, а в URL-адресі стоїть {{baseUrl}}, тож хост вводити не доведеться. Опис кожного запиту — той самий текст, що й на його сторінці в довіднику.

1. 1Розгорніть папку на бічній панелі — для початку добре підійде Astrology / Dasha — і клацніть запит.
2. 2Перевірте, що на вкладці Authorization вибрано успадкування від колекції. Це той apiKey, який ви щойно задали, тож заголовок вручну додавати не треба.
3. 3Натисніть Send. У тілі вже коректні значення, тож перший виклик спрацює без жодних правок.

Відкрийте вкладку Body і змініть значення. Чотири поля визначають майже все, що потрібно для карти. Якщо в них помилитися, ви зазвичай отримаєте не повідомлення про помилку, а відповідь, яка ледь помітно неправильна.

1. 1date_time — у форматі ISO 8601, і завжди зі зміщенням (+05:30) або Z у кінці. Значення без часового поясу читається як Asia/Kolkata, і для будь-кого за межами Індії карта непомітно зсувається.
2. 2latitude і longitude — десяткові градуси, а не градуси з хвилинами. Стежте за знаком: без мінуса Нью-Йорк опиниться в Китаї.
3. 3timezone_as_float — зміщення в годинах десятковим числом: 5.5 для Індії, -5 для Нью-Йорка.
4. 4Якщо JSON став неохайним, натисніть Beautify, а потім знову Send.

Панель відповіді відкривається внизу. У тілі — дані, а заголовки показують, як виклик вплинув на ваш баланс.

1. 1Body — JSON. Усе лежить під ключем data, поруч — message і is_error.
2. 2Headers: X-Credits-Cost — скільки коштує цей ендпоінт, X-Credits-Charged — скільки фактично списано, X-Credits-Remaining — баланс після виклику.
3. 3За будь-якого збою Charged показує 0: хибне тіло, неправильна дата, помилка на нашому боці. Експериментуйте сміливо — платите ви лише за виклики, які повернули дані.
4. 4Натисніть Save as example, щоб зберегти відповідь у запиті: команда побачить її структуру, не витрачаючи кредитів.

Коли запит робить те, що треба, Postman перепише його вашою мовою програмування. Відкрийте значок </> Code на правій панелі й виберіть cURL, Python, Node, PHP, Go чи будь-яку іншу.

У фрагменті {{baseUrl}} уже замінено справжнім хостом і є заголовок X-API-Key, тож код працює як є. Перед комітом замініть ключ на змінну середовища: у фрагменті справжні облікові дані.

Кнопка Run угорі колекції чи папки надсилає всі її запити по черзі. Так зручно перевірити, чи працює ключ для цілої категорії, або швидко прогнати smoke-тест після змін.

Пам’ятайте: кожен успішний виклик витрачає кредит. Запуск усіх 299 запитів коштуватиме 299 кредитів — і навіть більше, бо ендпоінт чату й два PDF-звіти коштують по 25. Запускайте окрему папку, а не всю колекцію, якщо тільки не робите це свідомо.

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

1. 1Коли оригінал змінюється, Postman пропонує на вашому форку pull changes.
2. 2Нові запити підтягнуться, а відредаговані тіла й задані змінні лишаться без змін.
3. 3У журналі змін видно, що й коли додано, тож ви знатимете, чи варто оновлюватися.