REST API: Definition & Examples

A REST API is an application programming interface designed around Representational State Transfer: constraints for exchanging representations of resources. For a quant, the distinction matters when retrieving quotes or submitting orders: the interface contract governs what a request means, while the data still needs validation before entering a calculation.

What makes an interface RESTful?

REST requires client–server separation, stateless requests, cache rules, a uniform interface and a layered system; downloading executable code is optional. Statelessness means each request supplies its necessary context, not that the service cannot store quotes or portfolios.

The uniform interface identifies resources, manipulates them through representations, makes messages self-descriptive and uses hypermedia links or controls to guide available actions. A quote resource and its JSON representation are different things; JSON is one possible format. HTTPS plus JSON and noun-shaped URLs alone do not establish REST conformance. These requirements come from Fielding’s original REST definition.

Reading is different from repeating

HTTP defines safe methods as requesting essentially read-only behaviour. Idempotency means identical requests have the same intended server effect as one request; responses need not match.

Method	Safe?	Idempotent by HTTP semantics?
GET	Yes	Yes
PUT	No	Yes
DELETE	No	Yes
POST	No	No general guarantee

A GET can still create logs or incur usage charges. PUT’s repeatability does not make it read-only. A DELETE retry can return a different status after the resource is gone. These properties concern the intended operation, not identical bytes or absence of every side effect. See HTTP Semantics, §§9.2.1–9.2.2.

For a timed-out order POST, the outcome may be unknown. Retry only with a documented duplicate-prevention contract or evidence the first operation was not applied. A provider-specific idempotency key needs its documented scope and lifetime; merely adding a header guarantees nothing. Check actual endpoint behaviour before relying on method labels. Rate-limit responses can use 429 with an optional Retry-After; respect the provider’s policy and bound retry attempts. RFC 6585 §4 defines that rate-limit response.

A quote fixture is only the body stage

Imagine a fictional service with the resource path /v1/quotes/ABC. A GET would request a representation of that resource. The following Python example starts with an authored string; it makes no HTTP request and is not a captured provider response. The price is a decimal string by this fictional schema’s design.

import json
from decimal import Decimal

body = '{"symbol":"ABC","price":"100.00","currency":"USD"}'
quote = json.loads(body)
if quote["symbol"] != "ABC" or quote["currency"] != "USD":
    raise ValueError("unexpected instrument or currency")
price = Decimal(quote["price"])
if not price.is_finite() or price <= 0:
    raise ValueError("price must be finite and positive")

quantity = 2
mark = quantity * price
print(f"{quantity} units at USD {price:.2f} = USD {mark:.2f}")
# 2 units at USD 100.00 = USD 200.00

The fictional holding is two units, each marked at USD 100, so its mark is USD 200 before fees or currency conversion. Decoding turns text into Python objects; it does not establish economic meaning. This narrow example assumes the documented fields and types. A live client must also enforce its complete schema, check quote time and timezone, instrument identity, price units and currency, and distinguish missing data from zero.

Fictional offline quote exchange: GET /v1/quotes/ABC identifies a resource; a JSON body provides price 100.00 USD per unit. Validation precedes marking 2 units at USD 200.00. No live request occurs.

A resource identifier, a response representation and a validated valuation input are separate steps. Fictional data; no network call was made.

For live access, use HTTPS, protected credentials and finite timeouts; inspect status and content type before decoding. Apply cache permissions and freshness rules, follow documented pagination, and record request parameters, retrieval time and the response snapshot used by research. The same resource URL can produce a changed quote later.

Continue with an ingestion boundary

APIs develops offline JSON parsing, required-field checks and the distinction between protocol success and data validity. Data Ingestion and APIs extends that boundary to dated price series, sorting and duplicate detection. Both have public previews; the full lessons require membership.

Sources

Roy Fielding, dissertation Chapter 5: REST, especially §§5.1–5.2.
IETF RFC 9110: HTTP Semantics, §§9.2–9.3.
IETF RFC 6585 §4: 429 Too Many Requests.
Python 3.14 documentation: JSON decoding. The offline example was executed with Python 3.14.4.
Python 3.14 documentation: decimal and finite-value checks.

What makes an interface RESTful?

Reading is different from repeating

A quote fixture is only the body stage

Continue with an ingestion boundary

Sources

Related terms

Application programming interface

JSON

Python