REST API
REST API — API в стиле REST (Representational State Transfer): каждый набор данных — ресурс со своим адресом, действие над ним задаёт метод HTTP, а сервер не хранит состояние клиента между запросами. Стиль описал Рой Филдинг в диссертации 2000 года.
Разбор запроса
Запрос ставок фандинга BTC по всем биржам:
curl "https://api.genesisarbitrage.com/v1/funding/rates?coin=BTC" \
-H "X-API-Key: $GENESIS_API_KEY"
| Часть | Значение | Смысл |
|---|---|---|
| Метод | GET | Прочитать данные |
| Базовый адрес | https://api.genesisarbitrage.com/v1 | Сервер и версия API |
| Ресурс | /funding/rates | Ставки фандинга бирж |
| Параметр | coin=BTC | Только BTC |
| Заголовок | X-API-Key | Ключ клиента |
Ответ приходит в JSON: в data у BTC список бирж со ставкой за интервал начисления (funding_pct) и ставкой, приведённой к 8 часам (funding_8h_pct). Без coin тот же ресурс вернёт все монеты. Поля описаны в разделе «Ставки фандинга».
Методы и состояние
Метод говорит серверу, что сделать с ресурсом. Значения методов задаёт стандарт HTTP, RFC 9110:
GET— получить данные; метод безопасный и ничего не меняет на сервере;POST— передать данные на обработку: на Binance так создают ордер (POST /api/v3/order);PUT— создать или заменить ресурс;DELETE— удалить: на Binance так отменяют ордер (DELETE /api/v3/order).
Genesis API только отдаёт данные, поэтому все его эндпоинты — GET.
«Без состояния» (stateless) значит, что каждый запрос несёт всё нужное: ключ, ресурс, фильтры. Сервер не помнит прошлых обращений, а GET ничего не меняет, поэтому запрос можно повторить после таймаута или ответа 503: результат зависит только от самого запроса и текущих данных. Чтобы не скачивать то, что не изменилось, Genesis API присылает ETag: запрос с If-None-Match получит 304, если данные прежние.
REST и WebSocket
| REST API | WebSocket | |
|---|---|---|
| Обмен | Запрос и ответ | Поток сообщений в обе стороны |
| Кто начинает | Клиент | После подключения — обе стороны |
| Подходит для | Снимков, фильтров, истории | Ленты сделок и стакана |
| В Genesis API | Все эндпоинты | Нет |
С REST обновления получают опросом: программа повторяет запрос через интервал. Genesis API обновляет отдачу раз в meta.freshness_sec секунд — от 60 на Trial до 5 на Max, — и опрашивать чаще нет смысла.
Смотрите также: эндпоинт, WebSocket, формат ответа, урок «Первый запрос к API: HTTP, заголовки и JSON».
Вопросы и ответы
Чем REST API отличается от API вообще?
API — любые правила обмена между программами. REST API — частный случай поверх HTTP: ресурсы по адресам, стандартные методы и запросы без привязки к прошлым.
В каком формате отвечает REST API?
Стиль REST формат не задаёт: это может быть JSON, XML или другой тип. Genesis API отвечает в JSON со сжатием gzip.