Intermediate
Writing
#api-docs
#technical-writing
#deprecation
Writing API Documentation
5 exercises — endpoint descriptions, deprecation notices, code example comments, and parameter specs.
0 / 22 completed
1 / 22
Which endpoint description follows API documentation best practices?
API endpoint documentation must include: HTTP method and path, what it returns, error responses with conditions, auth requirements, and rate limits. Option B hits all five. Option A omits the HTTP method, the path format, error handling, auth, and rate limits. Option C uses informal language ("pretty straightforward") and makes no technical claim. Option D is so vague it provides no value — "various user-related operations" could describe any endpoint.
2 / 22
Complete this API doc description: "This endpoint _____ (accept) a JSON body. The
email field _____ (be) required; if _____ (omit), the API _____ (return) a 400 Bad Request error."API documentation uses present simple throughout — it describes the permanent, designed behaviour of the API, not something that happens in the future or is happening right now. Accepts, is, returns — all present simple. For the conditional clause, "if omitted" is a reduced passive clause (short for "if [it is] omitted") — this is grammatical and very common in technical documentation because it is concise. "If it is omitted" (option C) is equally correct but slightly more verbose. "Will return" (option B) sounds like a prediction rather than a specification — present simple is the correct register for documented behaviour.
3 / 22
You are writing the description for a deprecation notice in API docs. Which notice is correct?
Deprecation notices require: the deprecated item, date deprecated, the replacement, removal date, and a migration path. Option B includes all five. Option A uses informal language ("old") and doesn't specify what the new endpoint is or when the old one disappears. Option C uses hedged language ("might not work") — deprecated APIs will be removed on a known date, not "might" stop working. Option D gives no dates, no replacement path, and no migration guide.
4 / 22
Which code example comment in API docs is most useful?
Code example comments in API docs should tell readers what the example demonstrates, what inputs are involved, and what to expect from the response. Option B: names the operation (create a user), names the key fields being set (email, name, role), and describes the response (201 status, created object, generated ID). This lets a developer read the comment and know exactly what they're looking at without running the code. Option A says nothing. Options C and D restate what the HTTP method already tells you — they add no new information.
5 / 22
Choose the correct phrasing for a parameter description: "The
limit parameter _____ (control) the number of results _____ (return) per page. It _____ (default) to 20 if _____ (not/provide). The maximum _____ (be) 100."Technical specifications use present simple throughout: controls, returned, defaults, is. These describe permanent, designed behaviour. Returned (past participle) acts as an adjective modifying "results" — "results returned per page" is a reduced relative clause ("results that are returned"). Defaults (present simple) for a designed fallback value. Not provided (past participle) in a reduced conditional ("if not provided" = "if it is not provided"). Is for a factual statement about the maximum. Option C uses "will be" for the maximum, which implies a future change — present simple is correct for a current, stable constraint.
6 / 22
During a code review of a new API endpoint, your colleague writes the following comment in the documentation:
`// This endpoint handles user authentication. It expects a JSON payload with 'username' and 'password' fields.
// If the credentials are invalid, it returns a 401 Unauthorized error.`
Which of the following best describes this comment's effectiveness and aligns with established API documentation practices?
A. It's perfectly adequate; basic descriptions like this are sufficient for most users. B. It's too verbose, focusing on the error response rather than the expected input. It should be more concise. C. It effectively communicates the endpoint's purpose and required parameters, providing a clear starting point for developers. D. The use of '//' is discouraged; all documentation should be in a dedicated section with proper formatting.
A. It's perfectly adequate; basic descriptions like this are sufficient for most users. B. It's too verbose, focusing on the error response rather than the expected input. It should be more concise. C. It effectively communicates the endpoint's purpose and required parameters, providing a clear starting point for developers. D. The use of '//' is discouraged; all documentation should be in a dedicated section with proper formatting.
Option B is correct because overly focusing on error responses detracts from clearly stating the expected input. Good API documentation prioritizes describing *what* the endpoint expects to receive. Options A and D are incorrect as they downplay the importance of a clear initial description and proper formatting respectively. Option C accurately reflects best practices – starting with the purpose and parameters is crucial for developer understanding.
7 / 22
You're reviewing a colleague's draft documentation for a new API endpoint that retrieves customer order details. The existing description reads: "This endpoint accepts an ID parameter and returns the corresponding order information."
During your review, you realize this is too vague. Which of the following revisions provides a more helpful and detailed description, aligning with best practices for API documentation?
Option 0 provides a comprehensive description outlining the endpoint's purpose, expected input (numeric ID), and the format of the returned JSON data. This level of detail is crucial for developers quickly understanding how to use the endpoint. The other options are too brief or lack specific information about the response structure, failing to adequately guide users.
8 / 22
You're reviewing a draft API endpoint description for a new service that calculates shipping costs. Your colleague writes: "This endpoint accepts a 'weight' and 'destination' parameter and returns the calculated shipping cost in USD.". During a code review with your team, another developer points out this description lacks crucial context. Which of the following revisions would be most effective in improving the clarity and usefulness of the documentation for developers unfamiliar with the service's pricing logic?
// This endpoint calculates shipping costs based on weight and destination.
// It uses a complex internal algorithm that considers factors like distance, package dimensions, and current fuel prices.
// The returned value is an estimate and may vary due to unforeseen circumstances.The original description is too simplistic and doesn't convey the complexity of the shipping cost calculation. Option C addresses this by providing crucial context about the factors influencing the estimate – distance, dimensions, and fuel prices. This helps developers understand *why* the cost might vary, improving their ability to interpret and use the endpoint effectively. Options A and D are insufficient because they either ignore the need for explanation or focus solely on a simplified interface without acknowledging the underlying complexity.
9 / 22
During a code review of a new API endpoint, your colleague writes the following comment in the documentation:
`// This endpoint handles user authentication. It expects a JSON payload with 'username' and 'password' fields.
// If the credentials are invalid, it returns a 401 Unauthorized error.`
Which of the following best describes this comment's effectiveness and aligns with established API documentation practices?
A. It's perfectly adequate; basic descriptions like this are sufficient for most users. B. It's too verbose, focusing on the error response rather than the expected input. It should be more concise. C. It effectively communicates the endpoint's purpose and required parameters, providing a clear starting point for developers. D. The use of '//' is discouraged; all documentation should be in a dedicated section with proper formatting.
A. It's perfectly adequate; basic descriptions like this are sufficient for most users. B. It's too verbose, focusing on the error response rather than the expected input. It should be more concise. C. It effectively communicates the endpoint's purpose and required parameters, providing a clear starting point for developers. D. The use of '//' is discouraged; all documentation should be in a dedicated section with proper formatting.
Option B is correct because overly focusing on error responses detracts from clearly stating the expected input. Good API documentation prioritizes describing *what* the endpoint expects to receive. Options A and D are incorrect as they downplay the importance of a clear initial description and proper formatting respectively. Option C accurately reflects best practices – starting with the purpose and parameters is crucial for developer understanding.
10 / 22
You're reviewing a colleague's draft documentation for a new API endpoint that retrieves customer order details. The existing description reads: "This endpoint accepts an ID parameter and returns the corresponding order information."
During your review, you realize this is too vague. Which of the following revisions provides a more helpful and detailed description, aligning with best practices for API documentation?
Option 0 provides a comprehensive description outlining the endpoint's purpose, expected input (numeric ID), and the format of the returned JSON data. This level of detail is crucial for developers quickly understanding how to use the endpoint. The other options are too brief or lack specific information about the response structure, failing to adequately guide users.
11 / 22
You're reviewing a draft API endpoint description for a new service that calculates shipping costs. Your colleague writes: "This endpoint accepts a 'weight' and 'destination' parameter and returns the calculated shipping cost in USD.". During a code review with your team, another developer points out this description lacks crucial context. Which of the following revisions would be most effective in improving the clarity and usefulness of the documentation for developers unfamiliar with the service's pricing logic?
// This endpoint calculates shipping costs based on weight and destination.
// It uses a complex internal algorithm that considers factors like distance, package dimensions, and current fuel prices.
// The returned value is an estimate and may vary due to unforeseen circumstances.The original description is too simplistic and doesn't convey the complexity of the shipping cost calculation. Option C addresses this by providing crucial context about the factors influencing the estimate – distance, dimensions, and fuel prices. This helps developers understand *why* the cost might vary, improving their ability to interpret and use the endpoint effectively. Options A and D are insufficient because they either ignore the need for explanation or focus solely on a simplified interface without acknowledging the underlying complexity.
12 / 22
During a code review of a new API endpoint, your colleague writes the following comment in the documentation:
`// This endpoint handles user authentication. It expects a JSON payload with 'username' and 'password' fields.
// If the credentials are invalid, it returns a 401 Unauthorized error.`
Which of the following best describes this comment's effectiveness and aligns with established API documentation practices?
A. It's perfectly adequate; basic descriptions like this are sufficient for most users. B. It's too verbose, focusing on the error response rather than the expected input. It should be more concise. C. It effectively communicates the endpoint's purpose and required parameters, providing a clear starting point for developers. D. The use of '//' is discouraged; all documentation should be in a dedicated section with proper formatting.
A. It's perfectly adequate; basic descriptions like this are sufficient for most users. B. It's too verbose, focusing on the error response rather than the expected input. It should be more concise. C. It effectively communicates the endpoint's purpose and required parameters, providing a clear starting point for developers. D. The use of '//' is discouraged; all documentation should be in a dedicated section with proper formatting.
Option B is correct because overly focusing on error responses detracts from clearly stating the expected input. Good API documentation prioritizes describing *what* the endpoint expects to receive. Options A and D are incorrect as they downplay the importance of a clear initial description and proper formatting respectively. Option C accurately reflects best practices – starting with the purpose and parameters is crucial for developer understanding.
13 / 22
You're reviewing a colleague's draft documentation for a new API endpoint that retrieves customer order details. The existing description reads: "This endpoint accepts an ID parameter and returns the corresponding order information."
During your review, you realize this is too vague. Which of the following revisions provides a more helpful and detailed description, aligning with best practices for API documentation?
Option 0 provides a comprehensive description outlining the endpoint's purpose, expected input (numeric ID), and the format of the returned JSON data. This level of detail is crucial for developers quickly understanding how to use the endpoint. The other options are too brief or lack specific information about the response structure, failing to adequately guide users.
14 / 22
You're reviewing a draft API endpoint description for a new service that calculates shipping costs. Your colleague writes: "This endpoint accepts a 'weight' and 'destination' parameter and returns the calculated shipping cost in USD.". During a code review with your team, another developer points out this description lacks crucial context. Which of the following revisions would be most effective in improving the clarity and usefulness of the documentation for developers unfamiliar with the service's pricing logic?
// This endpoint calculates shipping costs based on weight and destination.
// It uses a complex internal algorithm that considers factors like distance, package dimensions, and current fuel prices.
// The returned value is an estimate and may vary due to unforeseen circumstances.The original description is too simplistic and doesn't convey the complexity of the shipping cost calculation. Option C addresses this by providing crucial context about the factors influencing the estimate – distance, dimensions, and fuel prices. This helps developers understand *why* the cost might vary, improving their ability to interpret and use the endpoint effectively. Options A and D are insufficient because they either ignore the need for explanation or focus solely on a simplified interface without acknowledging the underlying complexity.
15 / 22
During a code review of a new API endpoint, your colleague writes the following comment in the documentation:
`// This endpoint handles user authentication. It expects a JSON payload with 'username' and 'password' fields.
// If the credentials are invalid, it returns a 401 Unauthorized error.`
Which of the following best describes this comment's effectiveness and aligns with established API documentation practices?
A. It's perfectly adequate; basic descriptions like this are sufficient for most users. B. It's too verbose, focusing on the error response rather than the expected input. It should be more concise. C. It effectively communicates the endpoint's purpose and required parameters, providing a clear starting point for developers. D. The use of '//' is discouraged; all documentation should be in a dedicated section with proper formatting.
A. It's perfectly adequate; basic descriptions like this are sufficient for most users. B. It's too verbose, focusing on the error response rather than the expected input. It should be more concise. C. It effectively communicates the endpoint's purpose and required parameters, providing a clear starting point for developers. D. The use of '//' is discouraged; all documentation should be in a dedicated section with proper formatting.
Option B is correct because overly focusing on error responses detracts from clearly stating the expected input. Good API documentation prioritizes describing *what* the endpoint expects to receive. Options A and D are incorrect as they downplay the importance of a clear initial description and proper formatting respectively. Option C accurately reflects best practices – starting with the purpose and parameters is crucial for developer understanding.
16 / 22
You're reviewing a colleague's draft documentation for a new API endpoint that retrieves customer order details. The existing description reads: "This endpoint accepts an ID parameter and returns the corresponding order information."
During your review, you realize this is too vague. Which of the following revisions provides a more helpful and detailed description, aligning with best practices for API documentation?
Option 0 provides a comprehensive description outlining the endpoint's purpose, expected input (numeric ID), and the format of the returned JSON data. This level of detail is crucial for developers quickly understanding how to use the endpoint. The other options are too brief or lack specific information about the response structure, failing to adequately guide users.
17 / 22
You're reviewing a draft API endpoint description for a new service that calculates shipping costs. Your colleague writes: "This endpoint accepts a 'weight' and 'destination' parameter and returns the calculated shipping cost in USD.". During a code review with your team, another developer points out this description lacks crucial context. Which of the following revisions would be most effective in improving the clarity and usefulness of the documentation for developers unfamiliar with the service's pricing logic?
// This endpoint calculates shipping costs based on weight and destination.
// It uses a complex internal algorithm that considers factors like distance, package dimensions, and current fuel prices.
// The returned value is an estimate and may vary due to unforeseen circumstances.The original description is too simplistic and doesn't convey the complexity of the shipping cost calculation. Option C addresses this by providing crucial context about the factors influencing the estimate – distance, dimensions, and fuel prices. This helps developers understand *why* the cost might vary, improving their ability to interpret and use the endpoint effectively. Options A and D are insufficient because they either ignore the need for explanation or focus solely on a simplified interface without acknowledging the underlying complexity.
18 / 22
During a Slack discussion about the new
PaymentService API, Sarah writes: 'Okay, so this endpoint takes a transactionId and returns the transaction details. It's important to note that if the transactionId is invalid, we'll get a 404.' Which of the following best describes how you should phrase this information in the API documentation for the getPaymentDetails endpoint? The best phrasing is option 1 because it clearly states the *purpose* of the parameter (retrieving details), specifies the expected format (a valid ID), and accurately describes what a 404 status code means in this context – an invalid ID. Options B and C are too informal, while D simply restates the error response without explaining its cause.
19 / 22
You're reviewing a code review comment on a new API endpoint: `// This endpoint handles user authentication. It expects a JSON payload with 'username' and 'password' fie…`. Which of the following is the MOST appropriate response to add to this documentation, focusing on clarity for other developers?
Option 1 provides the most critical information – *how* the endpoint expects the data (JSON format with specific fields). The other options are either irrelevant, technical details that should be in a separate section, or introduce potentially problematic instructions (hashing passwords) without context. It's about defining what the API *requires*, not how to implement security.
20 / 22
A senior developer asks you to document a new function in your codebase: `calculateShippingCost(weight, destination, shippingRate)`. Which of the following descriptions is MOST effective for this API?
Option 1 clearly defines the *purpose* of the function and lists its parameters with their expected data types. This provides immediate understanding to another developer. The other options focus on implementation details (algorithm, performance) that are not relevant for documentation; a good API description prioritizes what the user needs to know to *use* the function.
21 / 22
You're writing a PR description for a new API endpoint that returns product inventory data. The description currently reads: "This endpoint accepts an item ID and returns the available stock." Which of the following additions would significantly improve its quality?
Option 0 is correct because it specifies the *format* of the response (JSON with a specific field - stockLevel). This is crucial for developers to understand how to process the data. The other options are irrelevant details or best practices that belong in a separate section or code review comments; API documentation should focus on the immediate requirements of using the endpoint.
22 / 22
During a standup update, you're explaining your work on a new API. You state: 'I've implemented the
getUsers endpoint which takes a user ID and returns user details.' Your team lead asks, 'Can you elaborate on the expected response format?' Which of the following is the MOST appropriate follow-up to provide in the documentation? Option 0 directly addresses the team lead's question by specifying the *format* of the response (JSON with key-value pairs). This is the most important information for developers to know when using the endpoint. The other options are irrelevant details about architecture, deployment, or pagination – these belong in separate discussions or documentation sections.
Next up:
Meeting Agendas →
Frequently Asked Questions
What does the "Writing API Documentation — Writing Exercise" exercise cover?
Practice writing clear API documentation: endpoint descriptions, deprecation notices, code example comments, and parameter descriptions. 5 interactive exercises.
Is this exercise free to use?
Yes. Every exercise on CoderSlingo, including this one, is free to use with no account, sign-up, or paywall.
How many questions are in "Writing API Documentation — Writing Exercise"?
This exercise has 22 questions. Each one gives instant feedback with an explanation, so you can see exactly why an answer is right or wrong.
Do I need to create an account to save my progress?
No account is required. The progress bar and score are tracked in your browser for the current session -- the exercise is designed to be a quick, repeatable drill rather than something you resume later.
What happens if I get an answer wrong?
You'll see the correct answer highlighted immediately, along with a short explanation of why it's correct. Wrong answers aren't penalized beyond your score, and you can keep going through every question.
How is this exercise different from reading an article?
Articles explain vocabulary and concepts through prose, while exercises like this one are interactive drills -- multiple-choice questions -- that test and reinforce your recall of specific terms and phrasing.
Can I retry this exercise?
Yes -- use the "Try again" button on the results screen to reset your score and go through all the questions again from the start.
Where can I find more Email & Writing exercises?
Browse the full Email & Writing hub for related drills, or check the site-wide exercises index for other IT English topics.
Is this exercise suitable for beginners?
This exercise assumes basic familiarity with IT terminology. If a term feels unfamiliar, check the site Glossary for a plain-English definition before attempting the questions.
How often is new content like this published?
New exercises are added regularly across all categories, alongside new vocabulary sets and articles. Check back on the exercises hub to see what's new.