API Design Review Language | API Design Language Exercises

1 / 5

An architect proposes an API-first workflow: "We write the OpenAPI specification before any implementation code is written. Both the backend team and frontend team work against the spec from day one."

What is the primary advantage of this approach over an implementation-first approach?

Option C correctly identifies the core advantages of API-first (also called "spec-first" or "design-first") development. The other options contain common misconceptions:

Claim	Why it's wrong
A: guarantees bug-free implementation	A spec establishes the interface contract, not implementation correctness. Bugs in business logic, data processing, or edge cases are independent of spec quality.
B: only useful for public APIs	Internal APIs benefit equally — parallel development speed gains apply regardless of who consumes the API. Many teams find internal API contracts more important because there is no external documentation discipline forcing clarity.
D: legally binding, no deviations	A spec is a living design document, not a legal contract. Agile workflows expect iterative spec updates as understanding improves. The goal is early alignment, not contractual rigidity.

API-first benefits summary:

Parallel development — frontend can build against a mock server generated from the spec while backend implements
Design feedback — stakeholders (mobile, web, data teams) can review the API design before code is written and difficult to change
Shared language — "resource", "field name", "endpoint path" are agreed before ambiguous verbal communication causes drift
Contract testing — automated validation that implementation matches the spec catches regressions early

2 / 5

A developer proposes returning HATEOAS (Hypermedia as the Engine of Application State) links in all API responses — for example, a GET /orders/{id} response would include a _links object with URLs for cancel, refund, invoice actions.

When does HATEOAS add genuine value, and when is it over-engineering?

Option A correctly identifies when HATEOAS solves a real problem versus when it adds complexity without benefit. The other options contain factual errors:

Claim	Why it's wrong
B: universally required for RMM Level 3	Richardson Maturity Model Level 3 describes HATEOAS, but RMM is a descriptive model, not a prescription. Reaching Level 3 is not a goal in itself — it's one way to model an API. Many excellent, widely-used APIs operate at Level 2 by design.
C: only for browser HTML rendering	HATEOAS in JSON APIs (HAL, JSON:API, Siren) is well-established and has nothing to do with HTML rendering. The value is programmatic navigation, not visual rendering of links.
D: replaced by GraphQL introspection	GraphQL introspection reveals the schema and available queries, but GraphQL and REST are different paradigms. Neither replaces the other, and HATEOAS remains a valid REST-style pattern for dynamic navigation use cases.

When HATEOAS is the right choice:

Generic API consumers (SDKs that navigate multiple APIs without hardcoded knowledge)
Workflows with server-driven state machines (order lifecycle with state-dependent actions)
APIs designed for third-party developers who must not break when endpoints change

When HATEOAS is over-engineering:

Internal APIs consumed by services you own and deploy together
Simple CRUD APIs with stable, predictable endpoints
Tight-coupling scenarios where the client and server are always deployed simultaneously

3 / 5

A tech lead says: "We should implement RFC 7807 Problem Details for all error responses."

What does an RFC 7807-compliant error response contain, and how does it differ from a simple {"error": "Not found"}?

Option B accurately describes RFC 7807 "Problem Details for HTTP APIs" (also updated by RFC 9457). This is an IETF standard that addresses the lack of a consistent error response format across HTTP APIs.

Field	Type	Example value	Purpose
`type`	URI string	`https://example.com/errors/insufficient-funds`	Identifies error type programmatically; links to docs
`title`	string	"Insufficient Funds"	Short label — same for all occurrences of this error type
`status`	integer	`422`	HTTP status code (repeated in body for proxies that may strip headers)
`detail`	string	"Account #4829 balance is $12.00; transfer of $50.00 would exceed available funds."	Instance-specific explanation — what happened in this call
`instance`	URI string (optional)	`/errors/4829-2025-03-15T14:22Z`	Unique identifier for this specific error occurrence — for support tracking

Why RFC 7807 matters vs {"error": "Not found"}:

Programmatic error type identification: match on type URI, not fragile string comparison
Structured logging: standard fields make errors machine-parseable across services
Documentation linking: type URI can point to a human-readable error catalogue
Support workflows: instance URI lets support staff look up exactly what happened

4 / 5

A tech lead says: "For the activity feed endpoint, we should use cursor-based pagination rather than offset-based pagination."

Why is cursor-based pagination specifically preferred for feed endpoints over offset-based (?page=2&limit=20)?

Option D explains both the correctness problem (page drift) and the performance problem (O(N) scan) that make offset pagination unsuitable for real-time feeds.

Issue	Offset pagination	Cursor pagination
Page drift	Insert on page 1 shifts all subsequent pages → page 2 repeats the last item from page 1	Cursor marks the last seen position; inserts before the cursor don't affect the next page
Database performance	`SELECT … OFFSET 10000 LIMIT 20` — database scans 10,020 rows and discards 10,000	`SELECT … WHERE id > :cursor LIMIT 20` — index seek directly to position, O(log N)
Implementation complexity	Low — simple integer page number	Moderate — cursor must be stable, opaque, and tamper-resistant (often base64-encoded)
Random-access navigation	Supported — jump to page 50 directly	Not supported — must paginate forward sequentially from a known cursor

Cursor types:

ID-based: ?after=5a3f82c — simple, but only works if IDs are monotonically ordered
Timestamp-based: ?after=2025-03-15T14:22Z — works with time-ordered feeds; microsecond precision reduces collision risk
Opaque token: ?cursor=eyJpZCI6MTIzfQ== — base64-encoded payload; allows changing cursor implementation without API changes

5 / 5

An architect states: "Rate limiting and JWT authentication validation should both live in the API gateway layer, not be implemented separately in each microservice."

Which design principle or pattern is this recommendation based on?

Option A correctly identifies the gateway offloading pattern, which applies cross-cutting concern separation and DRY at the architectural level. The other options contain specific technical errors:

Claim	Why it's wrong
B: JWTs can only be validated by the issuing server	JWTs are self-contained by design — the signature is validated using the issuer's public key (asymmetric JWTs) or shared secret (symmetric). API gateways routinely validate JWTs without calling the issuing server, which is one of the core JWT use cases.
C: Microservices Independence Principle requires service-level auth	Microservice independence refers to deployment, scaling, and data independence — not to duplicating infrastructure concerns. No recognised microservices principle requires auth duplication. The fear of a single point of failure is addressed via gateway redundancy, not service-level auth duplication.
D: Principle of Least Privilege violated	Principle of Least Privilege is about which resources a principal can access, not about where validation occurs. The gateway validating a JWT does not grant the gateway any additional access rights — it only confirms the token's validity before forwarding the request.

What the API gateway offloading pattern handles:

Authentication (JWT validation, API key verification, OAuth token introspection)
Rate limiting and throttling
Request/response transformation and protocol translation
SSL/TLS termination
Request logging and distributed tracing injection
IP allowlisting and geo-blocking
CORS header management

The key question to ask: "Does this logic require knowledge of my service's business rules?" If no → gateway. If yes → service.