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"
| Part | Value | Meaning |
|---|---|---|
| Method | GET | Read data |
| Base URL | https://api.genesisarbitrage.com/v1 | Server and API version |
| Resource | /funding/rates | Exchange funding rates |
| Parameter | coin=BTC | BTC only |
| Header | X-API-Key | Client 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:
GET: retrieve data; the method is safe and changes nothing on the server;POST: send data for processing; Binance uses it to place an order (POST /api/v3/order);PUT: create or replace a resource;DELETE: remove; Binance uses it to cancel an order (DELETE /api/v3/order).
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 API | WebSocket | |
|---|---|---|
| Interaction | Request and response | Message stream both ways |
| Who starts | The client | Either side, once connected |
| Good for | Snapshots, filters, history | Trade and order book feeds |
| In Genesis API | Every endpoint | No |
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.