E6 · Publication Volume 28

API and Data-Contract Design

resources, queries, pagination, spatial subsets and versions

*resources, queries, pagination, spatial subsets and versions*

Resource, query, page, spatial subset and error contracts across an API boundary
Resource, query, page, spatial subset and error contracts across an API boundary

Learning objectives

This lesson is general and institution-neutral. It uses no real company, individual, property, project or identifiable place. Generic roles describe responsibilities only, and SYN-ARCH identifiers denote explicitly synthetic teaching evidence.

  • Frame the decision governed by resources, queries, pagination, spatial subsets and versions.
  • Model the relevant boundaries, states and contracts before selecting an implementation.
  • Define measurable invariants, failure evidence and a safe release consequence.
  • Produce a versioned API and data-contract specification with executable examples from synthetic evidence and defend its trade-offs.

Decision boundary

Design an API around decisions and stable domain resources, not around screens or database tables. For each consumer action, define the resource identity, allowed query, spatial and temporal subset, returned representation, consistency expectation, version context and failure meaning. A map viewport, a review queue and a reproducible analysis may need different shapes even when they refer to the same observations. Keep commands that change state distinct from queries that retrieve evidence. The boundary must say when a response is complete, partial, stale, redacted, approximate or superseded so a convenient response cannot be mistaken for authoritative evidence.

Core concepts

A contract includes syntax, semantics and operational behaviour. Syntax describes fields and types; semantics defines identity, units, coordinate reference, nullability, ordering and validity; operational behaviour defines authentication, limits, caching, retries and errors. Resource identifiers remain stable across representations. Collection endpoints expose bounded filters and deterministic ordering. Pagination is part of consistency: an offset over changing data can duplicate or omit records, while a cursor tied to a snapshot can preserve a declared view. Spatial subset parameters must state coordinate reference, axis order, boundary inclusion, precision and whether geometry is clipped, simplified or merely selected.

System model and contracts

Model the boundary as resource schema, query grammar, response envelope and problem schema. A resource carries stable identity, representation version, data version, validity, provenance link and domain fields. A collection response carries snapshot identity, deterministic order, page links or cursor, returned count and any known truncation. A spatial request includes an explicit reference and bounded extent. Problem responses use stable machine codes plus human-readable detail, affected field, retryability, correlation identity and links to rejected evidence where disclosure is permitted. Contract examples cover normal, empty, partial, redacted, stale, malformed, unsupported-version and over-limit cases.

Invariants and acceptance criteria

| Invariant | Test evidence | Release consequence | |---|---|---| | Every response declares the data and contract version needed for interpretation. | contract test and recorded counterexample | block publication | | Collection pagination is deterministic within a declared snapshot. | replay comparison and digest check | quarantine the artefact | | Spatial subsets declare reference, axis order and boundary semantics. | role-based acceptance trace | return the decision unresolved | | Problem responses carry stable codes without disclosing protected evidence. | failure injection and recovery record | retain the last verified version | | Contract examples are schema-valid and replayed by producer and consumer tests. | domain review against declared evidence | record an explicit review finding |

Quantitative engineering

Measure payload efficiency as P_e=B_{needed}/B_{transferred} for a declared consumer decision, and filter selectivity as S_f=n_{returned}/n_{eligible}. Report both with serialization, compression, cache state and geometry complexity. Pagination tests compare the union of all pages with the declared snapshot and check duplicates, omissions and order. Latency budgets use percentiles by operation and response class rather than a single mean. Limits constrain extent, feature count, vertices, requested fields, page size and computation cost. A smaller response is not automatically better if it removes provenance, units or uncertainty needed for interpretation.

Data quality, evidence and uncertainty

Derive contracts from representative decision traces and a field-level evidence dictionary. For every field, record definition, source, unit, reference, allowed states, precision, lineage, sensitivity and change policy. Examples are executable fixtures, not decorative snippets: validate them against schemas and replay them through both producer and consumer tests. Maintain counterexamples for ambiguous identifiers, mixed references, missing units, duplicate page boundaries, invalid geometry and changed records between pages. A contract cannot prove domain fitness; it can only preserve and expose the evidence needed for that review.

Interoperability and versioning

Publish the machine-readable schema, endpoint semantics, version policy and canonical examples as one reviewed package. Required fields cannot silently become optional; units, reference semantics or enumeration meanings cannot change under the same contract identity. Additive fields are safe only when consumers are required to ignore unknown optional members and round-trip behaviour is understood. Deprecation declares replacement, compatibility interval and removal condition. A digest identifies the exact contract package used by a release. Data-version and contract-version fields remain separate because a new dataset snapshot does not necessarily change the interface.

Security and professional responsibility

Authorise each resource, field and action using the requested version and spatial scope. Collection counts, extents, errors and timing can reveal protected information even when records are hidden, so disclosure policy covers metadata as well as values. Reject unbounded filters, excessive geometry, recursive expansion and expensive sort combinations before execution. Cursor tokens are opaque, integrity protected, scoped and expiring; they must not embed credentials or expose internal storage keys. Error detail supports correction without revealing secrets, query structure or the existence of inaccessible resources.

Operational workflow and observability

Run producer and consumer contract tests at every supported version. Observe request class, version, result class, response size, percentile latency, cache outcome, rejection code and retry behaviour without recording sensitive payloads. Compatibility monitoring detects unknown fields, unsupported versions and clients that continue using a deprecated path. Rate controls use cost and consequence, not only request count. When a contract defect is found, issue a corrected version, preserve the affected evidence window and notify dependent jobs; do not reinterpret historical responses under a silently changed schema.

Integration checkpoint

Connect the api and data-contract design artefact to the preceding volume architecture. Trace one synthetic object from source identity through the new boundary to a reviewed output, then trace one rejection or failure back to the earliest violated invariant. Update the architecture decision record with the chosen option, alternatives, assumptions, evidence, consequences, owner role, review state and triggers for reconsideration. A checkpoint passes only when another reviewer can reconstruct both the successful path and the blocked path without oral explanation.

Synthetic worked example

SYN-ARCH-05 first exposes a table-shaped endpoint with offset paging and an optional bounding box whose coordinate reference is unstated. During review, one inserted record shifts later pages and a consumer misses an interval. The revised contract uses stable resource identities, a snapshot-bound cursor, explicit reference and axis order, deterministic sort, field definitions and a structured rejection for an unsupported version. Executable fixtures include an empty subset and a geometry on the boundary. A replay proves every eligible identity appears exactly once, while a redaction test shows that inaccessible extents are not disclosed.

Practice and assessment

  1. Which decision and evidence justify each resource and query?
  2. How does a consumer know whether a page is complete and repeatable?
  3. Which spatial semantics must survive every representation?
  4. What change requires a new contract version rather than a new data version?

Assessed artefact: a versioned API and data-contract specification with executable examples. Submit the artefact with its source manifest, acceptance evidence, unresolved risks and a short explanation of why one plausible alternative was not selected.

Common failure modes

  • Mirroring database tables without defining domain resource semantics.
  • Using offset pagination over changing data without a snapshot contract.
  • Accepting a spatial extent without reference or axis-order rules.
  • Returning one generic error for malformed, forbidden and unavailable states.
  • Changing field meaning while retaining the same contract identity.

Sources and further reading