API является мостом между нашей аналитической платформой и вашими приложениями. Правильная интеграция позволяет получать доступ к богатым блокчейн-данным в реальном времени, создавать собственные дашборды и строить аналитические инструменты. В этом руководстве мы пошагово рассмотрим процесс интеграции нашего API, от получения ключей доступа до оптимизации запросов для production-окружения.

Начало работы: Получение API ключей

Первым шагом является регистрация на нашей платформе и получение API ключей. После создания аккаунта перейдите в раздел Developer Console, где вы сможете сгенерировать свой уникальный API ключ. Ключ представляет собой 64-символьную строку, которая будет использоваться для аутентификации всех ваших запросов.

Важно понимать разницу между различными типами ключей. Public API key подходит для клиентских приложений и имеет ограничения по количеству запросов. Private API key предназначен для серверных приложений и предоставляет расширенные возможности и более высокие лимиты. Secret key используется для подписи запросов в случаях, когда требуется повышенная безопасность.

Архитектура API

Наше API построено по принципам REST и использует стандартные HTTP методы. Все эндпоинты доступны по базовому URL: https://api.hibiscusespan.info/v1/. API возвращает данные в JSON формате, что обеспечивает легкую интеграцию с большинством современных языков программирования и фреймворков.

Структура запросов

Каждый запрос к API должен включать заголовок авторизации с вашим API ключом. Формат заголовка: Authorization: Bearer YOUR_API_KEY. Дополнительные параметры передаются либо в URL (для GET запросов), либо в теле запроса в формате JSON (для POST запросов).

Основные эндпоинты

API организован вокруг нескольких основных ресурсов. Эндпоинт /transactions предоставляет доступ к транзакционным данным, /addresses — к информации об адресах, /blocks — к данным о блоках, /analytics — к предварительно рассчитанным аналитическим метрикам. Каждый эндпоинт поддерживает различные параметры для фильтрации и пагинации данных.

Примеры интеграции

JavaScript / Node.js

Для работы с API в Node.js мы рекомендуем использовать библиотеку axios. Она предоставляет удобный интерфейс для выполнения HTTP запросов и автоматически обрабатывает JSON. Базовый пример получения списка транзакций включает настройку клиента с вашим API ключом и выполнение GET запроса к соответствующему эндпоинту.

Для production-приложений важно реализовать обработку ошибок и retry логику. API может возвращать различные коды состояния HTTP: 200 для успешных запросов, 400 для ошибок в параметрах, 401 для проблем с аутентификацией, 429 при превышении rate limit, 500 для внутренних ошибок сервера. Каждый случай требует соответствующей обработки.

Python

В Python экосистеме библиотека requests является стандартом де-факто для HTTP коммуникации. Создание простого клиента для нашего API занимает несколько строк кода. Важно правильно структурировать ваш код, вынося конфигурацию (включая API ключи) в переменные окружения для обеспечения безопасности.

Go

Go предлагает мощные инструменты для работы с HTTP из коробки. Стандартная библиотека net/http обеспечивает всё необходимое для интеграции с API. Go особенно хорош для создания высокопроизводительных сервисов, обрабатывающих большие объемы блокчейн-данных благодаря своей эффективной модели concurrency.

Работа с параметрами запросов

Большинство эндпоинтов API поддерживают богатый набор параметров для фильтрации и управления данными. Параметры network позволяют выбрать конкретную блокчейн-сеть (ethereum, bitcoin, polygon и т.д.). Временные фильтры date_from и date_to ограничивают результаты определенным временным диапазоном.

Пагинация реализована через параметры page и limit. По умолчанию API возвращает 100 записей, но вы можете увеличить это значение до 1000 для оптимизации количества запросов. Для больших датасетов рекомендуется использовать cursor-based пагинацию, которая более эффективна при работе с динамически изменяющимися данными.

Оптимизация производительности

Кеширование

Блокчейн-данные, особенно исторические, редко изменяются. Это делает их идеальными кандидатами для кеширования. Реализуйте локальное кеширование наиболее часто запрашиваемых данных. API включает заголовки Cache-Control и ETag, которые помогают эффективно управлять кешем на стороне клиента.

Batch-запросы

Для случаев, когда необходимо получить данные о нескольких адресах или транзакциях, используйте batch-эндпоинты. Вместо выполнения отдельных запросов для каждого адреса, вы можете отправить один запрос с массивом адресов, что значительно снижает latency и улучшает производительность.

Асинхронная обработка

Для запросов, требующих обработки больших объемов данных, API предлагает асинхронный режим работы. После инициации такого запроса вы получаете job ID, который можно использовать для проверки статуса выполнения и получения результатов по готовности. Это особенно полезно для генерации комплексных отчетов или экспорта больших датасетов.

Обработка ошибок и отладка

Надежная обработка ошибок критически важна для production-приложений. API возвращает детальные сообщения об ошибках в JSON формате, включающие код ошибки, описание и, при необходимости, дополнительные детали. Логируйте все ошибки для последующего анализа и мониторинга.

Для отладки мы предоставляем sandbox-окружение, доступное по адресу https://sandbox-api.hibiscusespan.info/v1/. В этой среде вы можете безопасно тестировать интеграцию без риска повлиять на production-данные или исчерпать свой rate limit.

Rate Limiting и квоты

Для обеспечения стабильности сервиса и справедливого распределения ресурсов мы применяем rate limiting. Бесплатный tier ограничен 100 запросами в час. Pro tier предлагает 10000 запросов в час. Enterprise tier предоставляет неограниченные запросы с гарантированным SLA.

Текущий статус ваших лимитов отображается в заголовках ответа: X-RateLimit-Limit показывает общий лимит, X-RateLimit-Remaining — оставшееся количество запросов, X-RateLimit-Reset — время сброса счетчика. Используйте эту информацию для имплементации адаптивной логики, которая замедляет запросы при приближении к лимиту.

Безопасность

Никогда не встраивайте API ключи напрямую в код, особенно в клиентских приложениях. Используйте переменные окружения или секретные хранилища. Для клиентских приложений рассмотрите возможность использования прокси-сервера, который будет выполнять запросы от имени клиента, скрывая ваш API ключ.

Всегда используйте HTTPS для коммуникации с API. Мы поддерживаем только безопасные соединения и автоматически перенаправляем HTTP запросы на HTTPS. Для дополнительной безопасности критичных операций используйте подпись запросов с помощью вашего secret key.

Webhooks для real-time уведомлений

Помимо polling API для получения обновлений, мы предлагаем систему webhooks для real-time уведомлений о событиях. Вы можете настроить webhooks для получения уведомлений о новых транзакциях для конкретных адресов, изменениях в балансах, подтверждениях транзакций и других событиях.

Настройка webhook выполняется через Dashboard или программно через API. Укажите URL вашего сервера, который будет принимать POST запросы с данными о событиях. Мы рекомендуем реализовать проверку подписи webhook-запросов для обеспечения их подлинности.

SDK и библиотеки

Для упрощения интеграции мы предоставляем официальные SDK для популярных языков программирования. JavaScript SDK доступен через npm, Python SDK — через pip, Go SDK — через go get. Эти библиотеки инкапсулируют низкоуровневые детали HTTP коммуникации и предоставляют идиоматичные интерфейсы для работы с API.

Заключение

Интеграция нашего API открывает широкие возможности для создания инновационных блокчейн-приложений. От простых информационных дашбордов до сложных аналитических систем — наше API предоставляет необходимые инструменты и данные. Следуйте best practices, изложенным в этом руководстве, и не стесняйтесь обращаться в нашу техническую поддержку при возникновении вопросов.