Как пользоваться коллекцией Postman

Все запросы в коллекции требуют аутентификации, поэтому без ключа данных не будет. Создать ключ можно бесплатно, а кредиты тратятся только на успешные вызовы.

1. 1Зарегистрируйтесь на occultapi.com/signup и подтвердите email.
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 вверху коллекции или папки отправляет все её запросы по порядку. Это удобно, чтобы проверить ключ на целой категории или прогнать быстрый тест после изменений.

Помните: каждый успешный вызов списывает кредит, так что прогон всей коллекции из 299 запросов обойдётся в 299 кредитов — и даже больше, ведь эндпоинт чата и два PDF-отчёта стоят по 25. Запускайте папку, а не всю коллекцию, если только вы не делаете это сознательно.

Коллекция генерируется из того же каталога, что и документация, поэтому новые эндпоинты появляются в ней вместе с API.

1. 1Когда оригинал меняется, Postman показывает в вашем форке пункт pull changes.
2. 2Он добавит новые запросы и не тронет ни изменённые вами тела, ни заданные переменные.
3. 3В журнале изменений видно, что и когда добавилось, — так понятно, стоит ли обновляться.