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 / 18
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 / 18
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 / 18
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
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 / 18
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.
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.
6 / 18
PR Description:
During a code review for the new payment processing service, a developer submits this PR description:
"Implemented API endpoint to initiate payments. Returns a success/failure status and transaction ID."
Which of the following best describes what's missing from this PR description, from an API design perspective?
Option A: The description clearly outlines all potential error scenarios and their corresponding HTTP status codes.
Option B: The description includes details about the expected data format for both successful and failed payment requests (e.g., request body schema).
Option C: The description specifies the rate limits applied to this endpoint, ensuring fair usage and preventing abuse.
Option D: The description explains the overall business impact of a successful or failed payment transaction – for example, how it affects order status and inventory.
This question assesses understanding of API documentation best practices. While error scenarios (Option A) and request/response formats (Option B) are important, they aren't the *primary* missing element in this PR description. Rate limiting (Option C), which manages resource consumption and prevents abuse, is a crucial design consideration for any public-facing API endpoint. Option D – business impact – is valuable context but doesn't directly address the API design itself. A good PR description should focus on how the API functions and its constraints.
7 / 18
A team is designing an API for a mobile application that allows users to track their fitness activities. During a discussion, a developer suggests returning all activity data in a single JSON response for each endpoint, regardless of the number of activities. Another team member raises concerns about potential performance issues and scalability. Which design consideration should be prioritized to address these concerns?
Option A: Ignoring the concerns raised by the other team member and implementing the single-response approach, as it's simpler to develop initially.
Option B: Implementing cursor-based pagination for the activity list endpoints, allowing clients to retrieve data in manageable chunks instead of a massive JSON blob.
Option C: Returning only the most recent activity record per endpoint, reducing the response size and improving performance.
Option D: Utilizing a server-sent events (SSE) stream to push updates to the client as activities are recorded, eliminating the need for polling.
The correct answer is B. Returning large JSON blobs, especially when dealing with lists of data like activity records, can quickly lead to performance bottlenecks and scalability issues on both the server and the client. Cursor-based pagination allows clients to efficiently retrieve data in smaller, manageable chunks, avoiding overwhelming the API and improving responsiveness. Options A and C are suboptimal because they exacerbate potential performance problems. Option D introduces a different architectural pattern (SSE) that might not be suitable for all use cases.
8 / 18
PR Description:
During a code review for the new payment processing service, a developer submits this PR description:
"Implemented API endpoint to initiate payments. Returns a success/failure status and transaction ID."
Which of the following best describes what's missing from this PR description, from an API design perspective?
Option A: The description clearly outlines all potential error scenarios and their corresponding HTTP status codes.
Option B: The description includes details about the expected data format for both successful and failed payment requests (e.g., request body schema).
Option C: The description specifies the rate limits applied to this endpoint, ensuring fair usage and preventing abuse.
Option D: The description explains the overall business impact of a successful or failed payment transaction – for example, how it affects order status and inventory.
This question assesses understanding of API documentation best practices. While error scenarios (Option A) and request/response formats (Option B) are important, they aren't the *primary* missing element in this PR description. Rate limiting (Option C), which manages resource consumption and prevents abuse, is a crucial design consideration for any public-facing API endpoint. Option D – business impact – is valuable context but doesn't directly address the API design itself. A good PR description should focus on how the API functions and its constraints.
9 / 18
A team is designing an API for a mobile application that allows users to track their fitness activities. During a discussion, a developer suggests returning all activity data in a single JSON response for each endpoint, regardless of the number of activities. Another team member raises concerns about potential performance issues and scalability. Which design consideration should be prioritized to address these concerns?
Option A: Ignoring the concerns raised by the other team member and implementing the single-response approach, as it's simpler to develop initially.
Option B: Implementing cursor-based pagination for the activity list endpoints, allowing clients to retrieve data in manageable chunks instead of a massive JSON blob.
Option C: Returning only the most recent activity record per endpoint, reducing the response size and improving performance.
Option D: Utilizing a server-sent events (SSE) stream to push updates to the client as activities are recorded, eliminating the need for polling.
The correct answer is B. Returning large JSON blobs, especially when dealing with lists of data like activity records, can quickly lead to performance bottlenecks and scalability issues on both the server and the client. Cursor-based pagination allows clients to efficiently retrieve data in smaller, manageable chunks, avoiding overwhelming the API and improving responsiveness. Options A and C are suboptimal because they exacerbate potential performance problems. Option D introduces a different architectural pattern (SSE) that might not be suitable for all use cases.
10 / 18
PR Description:
During a code review for the new payment processing service, a developer submits this PR description:
"Implemented API endpoint to initiate payments. Returns a success/failure status and transaction ID."
Which of the following best describes what's missing from this PR description, from an API design perspective?
Option A: The description clearly outlines all potential error scenarios and their corresponding HTTP status codes.
Option B: The description includes details about the expected data format for both successful and failed payment requests (e.g., request body schema).
Option C: The description specifies the rate limits applied to this endpoint, ensuring fair usage and preventing abuse.
Option D: The description explains the overall business impact of a successful or failed payment transaction – for example, how it affects order status and inventory.
This question assesses understanding of API documentation best practices. While error scenarios (Option A) and request/response formats (Option B) are important, they aren't the *primary* missing element in this PR description. Rate limiting (Option C), which manages resource consumption and prevents abuse, is a crucial design consideration for any public-facing API endpoint. Option D – business impact – is valuable context but doesn't directly address the API design itself. A good PR description should focus on how the API functions and its constraints.
11 / 18
A team is designing an API for a mobile application that allows users to track their fitness activities. During a discussion, a developer suggests returning all activity data in a single JSON response for each endpoint, regardless of the number of activities. Another team member raises concerns about potential performance issues and scalability. Which design consideration should be prioritized to address these concerns?
Option A: Ignoring the concerns raised by the other team member and implementing the single-response approach, as it's simpler to develop initially.
Option B: Implementing cursor-based pagination for the activity list endpoints, allowing clients to retrieve data in manageable chunks instead of a massive JSON blob.
Option C: Returning only the most recent activity record per endpoint, reducing the response size and improving performance.
Option D: Utilizing a server-sent events (SSE) stream to push updates to the client as activities are recorded, eliminating the need for polling.
The correct answer is B. Returning large JSON blobs, especially when dealing with lists of data like activity records, can quickly lead to performance bottlenecks and scalability issues on both the server and the client. Cursor-based pagination allows clients to efficiently retrieve data in smaller, manageable chunks, avoiding overwhelming the API and improving responsiveness. Options A and C are suboptimal because they exacerbate potential performance problems. Option D introduces a different architectural pattern (SSE) that might not be suitable for all use cases.
12 / 18
PR Description:
During a code review for the new payment processing service, a developer submits this PR description:
"Implemented API endpoint to initiate payments. Returns a success/failure status and transaction ID."
Which of the following best describes what's missing from this PR description, from an API design perspective?
Option A: The description clearly outlines all potential error scenarios and their corresponding HTTP status codes.
Option B: The description includes details about the expected data format for both successful and failed payment requests (e.g., request body schema).
Option C: The description specifies the rate limits applied to this endpoint, ensuring fair usage and preventing abuse.
Option D: The description explains the overall business impact of a successful or failed payment transaction – for example, how it affects order status and inventory.
This question assesses understanding of API documentation best practices. While error scenarios (Option A) and request/response formats (Option B) are important, they aren't the *primary* missing element in this PR description. Rate limiting (Option C), which manages resource consumption and prevents abuse, is a crucial design consideration for any public-facing API endpoint. Option D – business impact – is valuable context but doesn't directly address the API design itself. A good PR description should focus on how the API functions and its constraints.
13 / 18
A team is designing an API for a mobile application that allows users to track their fitness activities. During a discussion, a developer suggests returning all activity data in a single JSON response for each endpoint, regardless of the number of activities. Another team member raises concerns about potential performance issues and scalability. Which design consideration should be prioritized to address these concerns?
Option A: Ignoring the concerns raised by the other team member and implementing the single-response approach, as it's simpler to develop initially.
Option B: Implementing cursor-based pagination for the activity list endpoints, allowing clients to retrieve data in manageable chunks instead of a massive JSON blob.
Option C: Returning only the most recent activity record per endpoint, reducing the response size and improving performance.
Option D: Utilizing a server-sent events (SSE) stream to push updates to the client as activities are recorded, eliminating the need for polling.
The correct answer is B. Returning large JSON blobs, especially when dealing with lists of data like activity records, can quickly lead to performance bottlenecks and scalability issues on both the server and the client. Cursor-based pagination allows clients to efficiently retrieve data in smaller, manageable chunks, avoiding overwhelming the API and improving responsiveness. Options A and C are suboptimal because they exacerbate potential performance problems. Option D introduces a different architectural pattern (SSE) that might not be suitable for all use cases.
14 / 18
During a Slack discussion about the new 'user_profile' API, Sarah (the frontend developer) says: "I need all user details – name, email, address, preferences – returned in a single JSON response for each GET /users/{id} request. It's much easier than having to make multiple calls.". Which of the following best describes the potential problem with this approach from an API design perspective?
Sarah's suggestion prioritizes ease of implementation over efficiency. Returning all user details in a single response violates the principle of minimizing payload size, which is crucial for performance and bandwidth usage, especially on mobile devices. While RESTful principles are generally good, they shouldn't be prioritized at the expense of practical API design considerations. The correct answer focuses on the negative impact of large payloads.
15 / 18
Mark, a senior developer, is reviewing a PR for a new reporting endpoint. He comments: "The response should include links to related data – like the customer's orders and their invoices – using HATEOAS. This will allow clients to discover and navigate related resources dynamically.". What does Mark *primarily* advocate for regarding API design?
Mark's comment highlights the benefits of HATEOAS. HATEOAS fundamentally changes the API design by allowing clients to dynamically discover related resources without hardcoded URLs. This enhances flexibility and reduces coupling between the client and server. The other options represent outdated or less efficient approaches to API design.
16 / 18
During a standup meeting, David mentions: "We should use RFC 7807 Problem Details for *all* error responses. This gives the client more context about what went wrong and how to fix it.". What is a key characteristic of an RFC 7807-compliant error response compared to a simple JSON object like `{"error": "Not found"}`?
The core difference lies in the richness of information. A simple JSON object like `{"error": "Not found"}` provides minimal context. RFC 7807-compliant responses include detailed error descriptions, potential solutions, and links to relevant documentation – crucial for client-side error handling and debugging. This adds significant value beyond a basic status code.
17 / 18
A developer submits the following PR description:
"Implemented API endpoint to update user preferences. Returns a success/failure status and transaction ID.". The tech lead asks: "Should we include HATEOAS links in this response, pointing to related resources like the user's profile or their activity feed?", What is the *most* appropriate response?
While HATEOAS offers benefits, it's generally *not* necessary for a simple update operation like this. Adding complexity to the response without immediate benefit is often discouraged. The primary purpose of HATEOAS is to facilitate dynamic resource discovery and navigation, which isn't inherently required when just updating a single user preference.
18 / 18
During code review, Emily suggests: "For the inventory management API, we should use batch operations to update multiple product quantities at once. This reduces the number of API calls and improves performance.". What design pattern is Emily primarily referencing?
Emily is advocating for batching, which is a common and effective design pattern for optimizing API performance. Combining multiple operations into a single request reduces network overhead (fewer HTTP requests) and server processing time. Batching improves efficiency compared to making individual calls for each item.
What will I practice in "API Design Review Language | API Design Language Exercises"?
This is an API Design Language exercise set. It walks through 18 scenario-based multiple-choice questions built around real usage of API Design Language terminology that IT professionals encounter on the job.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to complete with no account, sign-up, or paywall.
How many questions are in this exercise?
This set contains 18 questions. Each one shows immediate feedback and a detailed explanation after you answer, so you learn the correct usage right away rather than waiting for a final score.
Do I need prior experience to complete this exercise?
No prior experience is required. Each question includes a full explanation covering the reasoning behind the correct answer, so the exercise itself teaches the API Design Language vocabulary as you go.
Can I retry the exercise if I get questions wrong?
Yes — use the "Try again" button on the results screen to reset your answers and go through all the questions again. There is no limit on attempts.
Is my progress saved?
Your answers and score for the current session are tracked in the browser as you go. No account or login is needed, and there is nothing to install.
What if I don't understand a term used in a question?
Read the explanation shown after you answer each question — it breaks down the correct term in plain English with a real-world example. You can also check the site Glossary for quick definitions.
How is this different from reading a blog article on the topic?
Exercises like this one are interactive drills that test and reinforce specific vocabulary through multiple-choice questions, while blog articles explain concepts in prose. Practising here after reading builds active recall, not just passive recognition.
Where can I find more API Design Language exercises?
See the API Design Language exercises hub for the full set of related pages, or browse all exercise categories from the main Exercises index.
Can I use this exercise to prepare for a technical interview?
Yes — API Design Language vocabulary comes up often in technical discussions and interviews. Pair this exercise with our dedicated Interview Preparation section for role-specific practice.