Genesis Arbitrage

Genesis Arbitrage · · 2 min read

REST API

A REST API is an API built in the REST style (Representational State Transfer): every data set is a resource with its own URL, the HTTP method sets the action, and the server keeps no client state between requests. Roy Fielding described the style in his 2000 doctoral dissertation.

Request breakdown

A request for BTC funding rates across all exchanges:

curl "https://api.genesisarbitrage.com/v1/funding/rates?coin=BTC" \
  -H "X-API-Key: $GENESIS_API_KEY"
PartValueMeaning
MethodGETRead data
Base URLhttps://api.genesisarbitrage.com/v1Server and API version
Resource/funding/ratesExchange funding rates
Parametercoin=BTCBTC only
HeaderX-API-KeyClient key

The response is JSON: data holds BTC with a list of exchanges, each with the rate per funding interval (funding_pct) and the rate normalized to 8 hours (funding_8h_pct). Without coin, the same resource returns every coin. The fields are described in the Funding rates section.

Methods and state

The method tells the server what to do with the resource. Method semantics are set by the HTTP standard, RFC 9110:

Genesis API only serves data, so all of its endpoints are GET.

Stateless means every request carries everything it needs: key, resource, filters. The server does not remember earlier calls and GET changes nothing, so a request can be repeated after a timeout or a 503: the result depends only on the request itself and the current data. To avoid downloading unchanged data, Genesis API sends an ETag: a request with If-None-Match gets 304 when nothing has changed.

REST vs WebSocket

REST APIWebSocket
InteractionRequest and responseMessage stream both ways
Who startsThe clientEither side, once connected
Good forSnapshots, filters, historyTrade and order book feeds
In Genesis APIEvery endpointNo

With REST you get updates by polling: the program repeats the request at an interval. Genesis API refreshes its output every meta.freshness_sec seconds, from 60 on Trial to 5 on Max, so polling faster gains nothing.

See also: endpoint, WebSocket, response format, lesson: your first API request with HTTP, headers and JSON.

Questions and answers

How is a REST API different from an API in general?

An API is any set of rules programs use to talk to each other. A REST API is a specific case over HTTP: resources at URLs, standard methods and requests that do not depend on earlier ones.

What format does a REST API respond in?

REST does not fix a format: it can be JSON, XML or another type. Genesis API responds in JSON with gzip compression.