API Field Description Vocabulary Quiz
Practice vocabulary for writing API field descriptions: enumerations, pattern constraints, deprecation notices, and constraint documentation.
0 / 26 completed
1 / 26
How should you document an enumeration field in an API description?
Enumeration fields should explicitly list all allowed values and explain what each one means: 'One of: "active" (account is enabled), "inactive" (account is disabled), "pending" (awaiting verification)'. Never leave consumers guessing.
2 / 26
A field description reads: 'This field is deprecated, use `user_id` instead.' What should a consumer developer do?
Deprecation notices signal that a field will be removed in a future version. Consumers should migrate to the replacement field as soon as possible to avoid breakage when the field is eventually removed.
3 / 26
What does documenting a 'pattern constraint' mean for a string field?
A pattern constraint describes the format a string must conform to, using a regex or plain-language description: 'ISO 8601 date-time', 'Must be a valid UUID v4', or 'Must match ^[A-Z]{2}-\d{6}$'. This prevents invalid input and clarifies expectations.
4 / 26
Why is it important to document 'constraint documentation' such as min/max values or string length limits?
Documenting constraints (minLength, maxLength, minimum, maximum, pattern) allows consumers to perform client-side validation and understand what values the API will accept, reducing error rates and integration issues.
5 / 26
When documenting an enumeration, a writer says 'describe the semantics, not just the values'. What does this mean?
Semantic documentation means explaining what 'pending' actually means in your domain (e.g. 'The order has been placed but not yet confirmed by the warehouse') rather than just listing it as an allowed string value.
6 / 26
During a code review of a new API endpoint for user profiles, Sarah comments on a field named `status` in the response:
'This field represents the current operational state of the user account. It's an enumeration with values like 'active', 'pending', and 'inactive'.'
David replies: 'That's helpful, but I need to know *why* it's 'pending'. Is there a specific reason users are pending?'
The question tests understanding of how to translate a technical definition into a usable explanation. While Sarah's initial description is technically correct (defining the *type* of data), David needs context—the 'why'. A good API description should not just list values but also explain their significance and potential reasons for different states, helping consumers understand when and why certain fields take specific values. The incorrect options highlight common pitfalls: focusing solely on the enumeration itself without tying it to business rules or providing actionable information.
7 / 26
PR Description
During a pull request to update the User Service API, Mark writes:
"The profile.email field is validated against a regular expression to ensure it conforms to RFC 5322."
Which of the following best describes what Mark is communicating?
profile.email field, specifying the rules it must adhere to for validation purposes.
C. Mark is describing the data type of the profile.email field as a string.
D. Mark is providing an example of a valid email address that can be used in the API.This question tests understanding of 'pattern constraints' within API documentation. Option B correctly identifies that Mark is defining *rules* for the
profile.email field – specifically, that it must match the RFC 5322 regular expression. The other options are incorrect; A misinterprets the purpose, C simply describes the data type, and D provides an example, not a description of the constraint itself. Understanding these constraints is crucial for developers to correctly handle the API response.8 / 26
During a pull request to update the User Service API, Liam writes: "The `profile.address` field accepts addresses conforming to the USPS standard format (e.g., 123 Main St, Anytown, CA 91234)." What is Liam primarily conveying about this field's documentation?
A. Liam is listing all possible valid address formats that can be used.
B. Liam is defining a data type for the field – it's a string representing an address.
C. Liam is specifying a constraint on the `profile.address` field, outlining the expected format according to USPS standards.
D. Liam is providing an example of a valid address that can be used in the API.
Liam is communicating a crucial *constraint* on the `profile.address` field. By stating the USPS standard format, he's defining the rules the API consumer must follow for inputting this data – preventing incorrect or invalid addresses from being processed. Options A and D are simply providing examples, while option B misrepresents the purpose of the documentation.
9 / 26
During a pull request to update the User Service API, Sarah writes: "The `profile.phone` field is documented with a minimum length of 10 characters and maximum length of 20 characters." What does Sarah primarily communicate about this field's documentation?
Sarah is communicating *constraints* on the `profile.phone` field – specifically, its minimum and maximum lengths. This is crucial for consumers to understand how the field should be populated and what constitutes valid input. Option A incorrectly frames this as purely technical detail; these constraints are fundamental to data integrity and validation. Options C and D misrepresent her statement regarding data type and example format respectively.
10 / 26
During a code review of a new API endpoint for user profiles, Sarah comments on a field named `status` in the response:
'This field represents the current operational state of the user account. It's an enumeration with values like 'active', 'pending', and 'inactive'.'
David replies: 'That's helpful, but I need to know *why* it's 'pending'. Is there a specific reason users are pending?'
The question tests understanding of how to translate a technical definition into a usable explanation. While Sarah's initial description is technically correct (defining the *type* of data), David needs context—the 'why'. A good API description should not just list values but also explain their significance and potential reasons for different states, helping consumers understand when and why certain fields take specific values. The incorrect options highlight common pitfalls: focusing solely on the enumeration itself without tying it to business rules or providing actionable information.
11 / 26
PR Description
During a pull request to update the User Service API, Mark writes:
"The profile.email field is validated against a regular expression to ensure it conforms to RFC 5322."
Which of the following best describes what Mark is communicating?
profile.email field, specifying the rules it must adhere to for validation purposes.
C. Mark is describing the data type of the profile.email field as a string.
D. Mark is providing an example of a valid email address that can be used in the API.This question tests understanding of 'pattern constraints' within API documentation. Option B correctly identifies that Mark is defining *rules* for the
profile.email field – specifically, that it must match the RFC 5322 regular expression. The other options are incorrect; A misinterprets the purpose, C simply describes the data type, and D provides an example, not a description of the constraint itself. Understanding these constraints is crucial for developers to correctly handle the API response.12 / 26
During a pull request to update the User Service API, Liam writes: "The `profile.address` field accepts addresses conforming to the USPS standard format (e.g., 123 Main St, Anytown, CA 91234)." What is Liam primarily conveying about this field's documentation?
A. Liam is listing all possible valid address formats that can be used.
B. Liam is defining a data type for the field – it's a string representing an address.
C. Liam is specifying a constraint on the `profile.address` field, outlining the expected format according to USPS standards.
D. Liam is providing an example of a valid address that can be used in the API.
Liam is communicating a crucial *constraint* on the `profile.address` field. By stating the USPS standard format, he's defining the rules the API consumer must follow for inputting this data – preventing incorrect or invalid addresses from being processed. Options A and D are simply providing examples, while option B misrepresents the purpose of the documentation.
13 / 26
During a pull request to update the User Service API, Sarah writes: "The `profile.phone` field is documented with a minimum length of 10 characters and maximum length of 20 characters." What does Sarah primarily communicate about this field's documentation?
Sarah is communicating *constraints* on the `profile.phone` field – specifically, its minimum and maximum lengths. This is crucial for consumers to understand how the field should be populated and what constitutes valid input. Option A incorrectly frames this as purely technical detail; these constraints are fundamental to data integrity and validation. Options C and D misrepresent her statement regarding data type and example format respectively.
14 / 26
During a code review of a new API endpoint for user profiles, Sarah comments on a field named `status` in the response:
'This field represents the current operational state of the user account. It's an enumeration with values like 'active', 'pending', and 'inactive'.'
David replies: 'That's helpful, but I need to know *why* it's 'pending'. Is there a specific reason users are pending?'
The question tests understanding of how to translate a technical definition into a usable explanation. While Sarah's initial description is technically correct (defining the *type* of data), David needs context—the 'why'. A good API description should not just list values but also explain their significance and potential reasons for different states, helping consumers understand when and why certain fields take specific values. The incorrect options highlight common pitfalls: focusing solely on the enumeration itself without tying it to business rules or providing actionable information.
15 / 26
PR Description
During a pull request to update the User Service API, Mark writes:
"The profile.email field is validated against a regular expression to ensure it conforms to RFC 5322."
Which of the following best describes what Mark is communicating?
profile.email field, specifying the rules it must adhere to for validation purposes.
C. Mark is describing the data type of the profile.email field as a string.
D. Mark is providing an example of a valid email address that can be used in the API.This question tests understanding of 'pattern constraints' within API documentation. Option B correctly identifies that Mark is defining *rules* for the
profile.email field – specifically, that it must match the RFC 5322 regular expression. The other options are incorrect; A misinterprets the purpose, C simply describes the data type, and D provides an example, not a description of the constraint itself. Understanding these constraints is crucial for developers to correctly handle the API response.16 / 26
During a pull request to update the User Service API, Liam writes: "The `profile.address` field accepts addresses conforming to the USPS standard format (e.g., 123 Main St, Anytown, CA 91234)." What is Liam primarily conveying about this field's documentation?
A. Liam is listing all possible valid address formats that can be used.
B. Liam is defining a data type for the field – it's a string representing an address.
C. Liam is specifying a constraint on the `profile.address` field, outlining the expected format according to USPS standards.
D. Liam is providing an example of a valid address that can be used in the API.
Liam is communicating a crucial *constraint* on the `profile.address` field. By stating the USPS standard format, he's defining the rules the API consumer must follow for inputting this data – preventing incorrect or invalid addresses from being processed. Options A and D are simply providing examples, while option B misrepresents the purpose of the documentation.
17 / 26
During a pull request to update the User Service API, Sarah writes: "The `profile.phone` field is documented with a minimum length of 10 characters and maximum length of 20 characters." What does Sarah primarily communicate about this field's documentation?
Sarah is communicating *constraints* on the `profile.phone` field – specifically, its minimum and maximum lengths. This is crucial for consumers to understand how the field should be populated and what constitutes valid input. Option A incorrectly frames this as purely technical detail; these constraints are fundamental to data integrity and validation. Options C and D misrepresent her statement regarding data type and example format respectively.
18 / 26
During a code review of a new API endpoint for user profiles, Sarah comments on a field named `status` in the response:
'This field represents the current operational state of the user account. It's an enumeration with values like 'active', 'pending', and 'inactive'.'
David replies: 'That's helpful, but I need to know *why* it's 'pending'. Is there a specific reason users are pending?'
The question tests understanding of how to translate a technical definition into a usable explanation. While Sarah's initial description is technically correct (defining the *type* of data), David needs context—the 'why'. A good API description should not just list values but also explain their significance and potential reasons for different states, helping consumers understand when and why certain fields take specific values. The incorrect options highlight common pitfalls: focusing solely on the enumeration itself without tying it to business rules or providing actionable information.
19 / 26
PR Description
During a pull request to update the User Service API, Mark writes:
"The profile.email field is validated against a regular expression to ensure it conforms to RFC 5322."
Which of the following best describes what Mark is communicating?
profile.email field, specifying the rules it must adhere to for validation purposes.
C. Mark is describing the data type of the profile.email field as a string.
D. Mark is providing an example of a valid email address that can be used in the API.This question tests understanding of 'pattern constraints' within API documentation. Option B correctly identifies that Mark is defining *rules* for the
profile.email field – specifically, that it must match the RFC 5322 regular expression. The other options are incorrect; A misinterprets the purpose, C simply describes the data type, and D provides an example, not a description of the constraint itself. Understanding these constraints is crucial for developers to correctly handle the API response.20 / 26
During a pull request to update the User Service API, Liam writes: "The `profile.address` field accepts addresses conforming to the USPS standard format (e.g., 123 Main St, Anytown, CA 91234)." What is Liam primarily conveying about this field's documentation?
A. Liam is listing all possible valid address formats that can be used.
B. Liam is defining a data type for the field – it's a string representing an address.
C. Liam is specifying a constraint on the `profile.address` field, outlining the expected format according to USPS standards.
D. Liam is providing an example of a valid address that can be used in the API.
Liam is communicating a crucial *constraint* on the `profile.address` field. By stating the USPS standard format, he's defining the rules the API consumer must follow for inputting this data – preventing incorrect or invalid addresses from being processed. Options A and D are simply providing examples, while option B misrepresents the purpose of the documentation.
21 / 26
During a pull request to update the User Service API, Sarah writes: "The `profile.phone` field is documented with a minimum length of 10 characters and maximum length of 20 characters." What does Sarah primarily communicate about this field's documentation?
Sarah is communicating *constraints* on the `profile.phone` field – specifically, its minimum and maximum lengths. This is crucial for consumers to understand how the field should be populated and what constitutes valid input. Option A incorrectly frames this as purely technical detail; these constraints are fundamental to data integrity and validation. Options C and D misrepresent her statement regarding data type and example format respectively.
22 / 26
During a Slack conversation regarding the new `payment_method` API endpoint, David asks: 'Can you confirm that this field uses a standard ISO 4217 currency code?' What does David primarily mean when he refers to 'ISO 4217' in this context?
ISO 4217 is an international standard for currency codes. David's question focuses on ensuring consistency in how monetary values are represented across different systems using this standard. The ISO 4217 code provides a unique identifier for each currency, avoiding ambiguity and facilitating interoperability between systems – failing to use it would lead to data inconsistencies.
23 / 26
In a pull request update for the 'product_details' API, Elena writes: 'The `product.price` field is documented with its unit of measurement as 'USD'.' What does Elena's comment primarily communicate about this specific field?
Elena's statement highlights the importance of documenting the units associated with a numeric field. Specifying 'USD' clarifies that the `product.price` represents a monetary value in US Dollars. Without this detail, developers would be unsure how to interpret and use the numerical data correctly – it's crucial for avoiding misinterpretations.
24 / 26
During a code review of an API response for 'order_status', Ben states: 'The `order.status` field uses an enumerated type with values like 'Pending', 'Shipped', and 'Delivered'.' What is Ben primarily describing?
Ben is describing an *enumerated type*, which is a fundamental concept in API design. Enumerated types restrict possible values to a predefined set (e.g., 'Pending', 'Shipped', 'Delivered'), ensuring data consistency and simplifying validation logic on the server-side. This contrasts with free-text input, where values could be arbitrary and difficult to manage.
25 / 26
In a standup update, Chloe mentions: 'We've added a field called `user.country_code` to the API response for user profiles, using the ISO 3166-1 alpha-2 code standard.' What is the primary purpose of this new field?
The ISO 3166-1 alpha-2 code standard provides a standardized way to represent countries using two-letter codes. Using this field allows the system to reliably identify and categorize users based on their geographic location – essential for tasks like localization, reporting, and potentially compliance requirements.
26 / 26
During a code review of an API endpoint for 'customer_addresses', Maria writes: 'The `address.city` field is validated against a list of recognized city names.' What is Maria's comment primarily focused on?
Maria's comment emphasizes data validation – ensuring that the `address.city` field contains a legitimate and recognized city name. This prevents errors caused by typos or invalid input, improving the overall reliability and accuracy of the address data. Validation is crucial for downstream processes like shipping and billing.
Frequently Asked Questions
What will I practice in "API Field Description Vocabulary Quiz"?
This is an API Spec Writing exercise set. It walks through 26 scenario-based multiple-choice questions built around real usage of API Spec Writing 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 26 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 Spec Writing 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 Spec Writing exercises?
See the API Spec Writing 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 Spec Writing vocabulary comes up often in technical discussions and interviews. Pair this exercise with our dedicated Interview Preparation section for role-specific practice.