API Definition: what it is
API definition is the documented contract that describes how a client should call an API and how the API will respond. It typically includes endpoint routes, request/response formats (for example, JSON fields), data types, required vs. optional parameters, authentication and permissions, rate limits, error formats, and any stated timing or ordering expectations.
In an automated trading context, the API definition matters because every downstream step—data ingestion, signal logic, execution decisions, and reporting—depends on what the API guarantees versus what it merely “tries” to provide. The key evaluation goal is to understand which parts are stable mechanics and which parts can vary with market conditions, system load, and provider policies.
How to check an API definition (objective checklist)
- Contract completeness (afvinkpunten)
- Endpoints and methods are explicitly listed.
- Request and response schemas are defined, including field meanings and data types.
- Examples exist for normal responses and each documented error type.
- Authentication and authorization requirements are stated (for example, how credentials are supplied and what access is allowed).
- Behavior details (the “how it works” part)
- Confirm whether the API defines ordering or consistency across calls (for example, whether “latest” is tied to a timestamp).
- Check how timestamps are represented (format, time zone, and whether they reflect event time or processing time).
- Verify how pagination, filtering, and limits work, including maximum page sizes and default values.
- Variable conditions vs. stable mechanics
- Separate stable elements (schema, parameter rules, documented error codes) from variable elements (latency, gaps in data, market movement, throttling due to load).
- Treat any statement about “real-time” or “streaming” as a behavioral claim you should verify through tests or sample responses, not as a fixed promise.
- Evidence and document proof Look for implementation artifacts that let you validate the contract:
- Documentation that includes sample payloads and error responses.
- Versioning policy describing how changes are introduced and for how long old versions remain supported.
- Test resources such as sandbox environments, mock endpoints, or recorded example calls.
- Clear limitation statements (rode vlaggen) Identify gaps where documentation is silent or ambiguous:
- Missing definitions for critical fields.
- Unclear error semantics (for example, whether an error is retryable).
- No description of backpressure, rate limiting behavior, or what happens during partial outages.
Evidence or example: what “verification” means
A practical example of evidence-based evaluation is to run scripted calls that cover:
- A “happy path” request and confirm that response fields match the documented schema.
- At least one boundary condition, such as an invalid parameter that should trigger a documented error.
- A latency/timing check by measuring round-trip time and comparing it with any stated timing expectations.
Assumption example (state it explicitly): if you measure response time from your own system clock, you assume your clock is reasonably synchronized. Without that assumption, timing comparisons can be misleading.
Limitations and failure modes to account for
At minimum, evaluate at least one material failure mode:
- Data gaps: the API may return incomplete history, missing events, or delayed updates.
- Latency and ordering issues: even if timestamps exist, call ordering may not match event ordering.
- Rate limiting or throttling: excessive requests can lead to delays or structured errors.
- Schema drift: API versions may change fields, types, or required parameters.
- Authentication/permission failures: tokens may expire or access scopes may differ by environment.
Historical relationships do not establish future results. Even if sample responses look consistent, future behavior can change when the provider updates services or when system load and market volatility change. Outcomes also vary with costs, execution method, and jurisdiction, so treat API definition as a contract description, not a performance guarantee.
Verification criteria and next questions
Use a clear “klaarcriterium” (done-criteria) before integrating:
- You can map every required parameter and every returned field to a documented meaning.
- You can reproduce documented success and error responses in a test environment.
- You have documented assumptions for timing, retries, and data completeness.
- You have a plan for handling rate limits, unknown fields, and version changes.
Next questions to ask during evaluation:
- What exactly is the API’s documented consistency model for timestamps and ordering? - Which errors are retryable, and what backoff guidance is provided?