REST APIs

Quick answer: A REST API is a request/response interface over HTTP in which each call asks a named endpoint to read or change a resource and returns exactly one structured reply with a status code indicating the outcome.

In simple words

REST is a question-and-answer style of talking to a server. Your code sends one HTTP request — for example, place this order — and gets back one HTTP response with a code and a body. Each call is self-contained: you say what you want, the server does it and replies, and the conversation ends until you ask again.

Purpose

REST gives trading systems a simple, well-understood way to perform discrete actions — placing an order, cancelling it, fetching positions — where a single definite answer per request is exactly what you need.

Professional explanation

The request/response model

Every REST interaction is one request producing one response. The request carries a method (the verb), a URL (which resource), headers (metadata such as authentication and content type) and optionally a body (the payload, usually JSON). The server processes it and returns a response with a status code, headers and a body. Crucially, standard REST is stateless per call: the server does not remember your previous request, so everything needed to interpret this one — including your auth token — travels with it. This statelessness makes REST easy to scale and reason about, but it also means REST cannot, by itself, push you updates; you only learn something changed by asking again.

Endpoints and resources

A REST API is organised around resources, each addressed by an endpoint URL. A broker API might expose /orders for the order collection, /orders/{id} for a specific order, /positions for open positions and /instruments for the tradable universe. The path names the thing; the method names the operation on it. Good API design keeps endpoints noun-like and predictable, so /orders with a POST creates an order and /orders with a GET lists them. Reading the documentation to learn the exact endpoint names, required fields and response shapes is the unavoidable first step of integrating any broker.

HTTP methods and their semantics

The verbs carry meaning that matters for safety. GET reads and must not change state, so it is safe to repeat freely. POST typically creates something — an order — and is generally not idempotent, meaning two identical POSTs can create two orders. PUT and PATCH modify an existing resource, and DELETE removes or cancels one; these are usually idempotent, so repeating them lands in the same final state. This distinction is not academic in trading: because POST is not naturally idempotent, a retried order-placement POST can double-send, which is precisely why order creation needs explicit idempotency safeguards while a cancel (DELETE) can be retried more freely.

Status codes: the outcome signal

The three-digit status code is the first thing your code must inspect. 2xx means success — 200 OK for a completed read, 201 Created for a new order. 4xx means the request was wrong and will keep failing unless you change it: 400 bad request, 401 unauthorised (auth failed), 403 forbidden (not allowed), 404 not found, 429 too many requests (rate limited). 5xx means the server failed — 500 internal error, 502/503/504 gateway or availability problems — and may succeed if retried later. The families map cleanly onto behaviour: never retry a 400 unchanged, back off and retry a 429 or 5xx, and treat a 401 as a signal to refresh credentials. Reading the numeric code and the error body together, rather than assuming success, is fundamental.

Payloads, content types and parsing

Most broker REST APIs speak JSON: your request body is a JSON object of order fields, and the response body is JSON you must parse. The Content-Type header declares the format, and mismatches (sending form-encoded data where JSON is expected, or vice versa) produce confusing 400s. Your client should validate that the response is well-formed and contains the fields you expect before using them — a 200 status with an unexpected body shape, perhaps due to an API version change, can otherwise be misread as a successful order. Defensive parsing, not blind trust, is the norm.

When to use REST in a trading system

REST is the right tool for actions and point-in-time queries: place, modify, cancel an order; fetch current positions, funds, margins, holdings; pull a batch of historical candles. It is the wrong tool for continuous real-time data, because polling a REST endpoint every fraction of a second to simulate a live feed is wasteful, laggy and rate-limit-hostile — that job belongs to a WebSocket. A clean architecture uses REST for the transactional spine of the system and a stream for the firehose of market ticks and order updates.

Common HTTP methods in a broker API

Practical example

Advantages

• Simple, universal and well-documented — every language has an HTTP client
• Stateless calls are easy to test, log, replay and reason about individually
• Status codes give a clear, standard signal of success, client error or server error
• Ideal for discrete actions and point-in-time queries where one definite answer is wanted

Limitations

• Cannot push updates — you only learn of changes by polling, which adds latency and load
• POST is not idempotent by default, so retried order requests can double-send without safeguards
• Each call carries overhead (connection, headers, auth), making high-frequency polling inefficient
• A 200 status does not guarantee the body is the shape you expect after an API version change
• Aggressive polling quickly runs into rate limits and bans

Common mistakes

• Treating any 2xx as success without parsing the body and confirming the order state
• Retrying a failed POST order request blindly, creating duplicate orders
• Retrying a 400 (bad request) unchanged instead of fixing the malformed input
• Polling a REST quote endpoint in a tight loop instead of subscribing to a WebSocket
• Ignoring the 401 vs 429 distinction — refreshing tokens when you should be backing off, or vice versa
• Assuming all brokers use identical endpoint names, fields and status conventions

Professional usage

Professional systems wrap the raw HTTP client in a typed layer that centralises authentication, retries, timeouts and status-code handling, so strategy code never touches URLs directly. They map status-code families to explicit policies (retry, refresh, fail, alert), attach client-side idempotency references to order POSTs, and set aggressive but sane timeouts so a hung request cannot stall the whole loop. Every request and response is logged with correlation ids for post-trade reconciliation and debugging.

Frequently asked questions

Voice search & related questions

Natural-language questions people ask about REST APIs.

Sources & references

Last reviewed 11 July 2026. Educational content only — not investment advice. Markets and rules change; verify current conventions with SEBI, NSE/BSE and your broker.