OpenAPI Design Essentials: Resource Modeling, Validation, and Versioning Quiz

Test your knowledge of API design fundamentals with a focus on OpenAPI, covering resource modeling, schema-based validation, versioning, and ensuring backward compatibility. This quiz is ideal for those aiming to build robust and maintainable APIs using standardized practices.

1. Resource Naming Conventions

   Which approach is most recommended when modeling a collection resource in OpenAPI, for instance, to expose a list of books?

   1. /bookList
   2. /getBooks
   3. /books-list
   4. /books

   Explanation: /books aligns with RESTful conventions where plural nouns represent collections, making it easily understandable and standard. '/bookList' and '/books-list' use inconsistent naming or unnecessary descriptors. '/getBooks' incorrectly uses an action verb instead of a resource noun, which does not align with RESTful best practices.

2. Schema Validation Purpose

   What is the main advantage of using schema-based validation for an API's request payload in the OpenAPI specification?

   1. Ensures payload structure and data types before processing
   2. Increases API response speed
   3. Allows direct database updates
   4. Disables authentication requirements

   Explanation: Schema-based validation enforces rules on input structure and types, reducing runtime errors and promoting data consistency. While it does not inherently increase response speed or update databases, and it has no effect on authentication requirements, it is crucial for input validation and API reliability.

3. Versioning Strategy Decision

   If you need to introduce a breaking change, such as removing a field from your API response, which versioning strategy is most appropriate according to OpenAPI best practices?

   1. Increment the major version and update the API path or header
   2. Make the change silently without versioning
   3. Add a deprecation notice but keep the same version
   4. Only change the documentation

   Explanation: Breaking changes should trigger a major version increment and clear communication through the path (e.g., '/v2/') or headers for transparency. Making silent changes or only updating documentation can break existing clients unintentionally. Deprecation without versioning is insufficient for breaking changes.

4. Reference Object Reuse

   When designing shared data structures such as 'User' or 'Address' in OpenAPI schemas, what is the best practice for maintaining consistency?

   1. Define the object schema once and use references where needed
   2. Duplicate the schema definition in every endpoint
   3. Use inline type definitions only
   4. Omit the schema and use free-form objects

   Explanation: Defining schemas once and referencing them promotes consistency and easier maintenance. Duplicating schemas increases risk of inconsistency, while omitting validation or using only inline definitions can make maintenance and validation difficult.

5. HTTP Status Codes in OpenAPI

   Which HTTP status code should be specified in OpenAPI for a successful resource creation via POST, such as adding a new order?

   1. 200
   2. 201
   3. 400
   4. 204

   Explanation: 201 indicates resource creation, matching the semantics of POST for creating new entities. 200 is for a general successful request but not specific to creation. 204 means 'no content', which isn't appropriate when a new resource is created. 400 is used for client errors.

6. Schema Required Properties

   In an OpenAPI schema, how do you specify that a property like 'email' must always be present in client requests?

   1. Set 'email' as type: mandatory
   2. Add 'email' to the 'required' array
   3. List 'email' under 'optionalFields'
   4. Mark 'email' as 'unique:true'

   Explanation: Listing the property in the 'required' array is the established way to enforce its presence. Setting type as 'mandatory' or 'unique:true' are not standard schema keywords. 'optionalFields' has no meaning in OpenAPI schema specifications.

7. Backward Compatibility Principle

   Which change is generally considered backward compatible in API schema evolution?

   1. Changing a property's data type from string to integer
   2. Removing a field used by client applications
   3. Adding a new optional property to the response object
   4. Renaming an existing required field

   Explanation: Adding optional properties does not affect existing clients. Renaming or removing fields, or altering types, can break clients expecting the previous structure and are not backward compatible.

8. Parameter Location Choice

   Where should resource identifiers, such as 'userId', be placed in an OpenAPI path for fetching a single item, for example retrieving a user profile?

   1. In request headers
   2. In the path, like /users/{userId}
   3. As a query parameter like /users?userId=123
   4. In the POST body

   Explanation: Resource identifiers for singular resources fit best in the path as path parameters for clarity and proper URL structure. Placing IDs in the body or headers is unconventional for GET requests, and query parameters are used for filtering collections rather than fetching a specific resource.

9. Error Response Schema Design

   Which of the following is a recommended practice when defining error responses in OpenAPI specifications?

   1. Leave error response schema undefined
   2. Use a consistent error structure including code and message properties
   3. Return only plain text error strings
   4. Use descriptive HTML pages as error bodies

   Explanation: A structured error object (with code and message) facilitates error handling and debugging across clients. Plain text or HTML responses are difficult for automated processing, while leaving schemas undefined leads to unpredictable responses.

10. Deprecating Fields

    How should you indicate in an OpenAPI schema that a field, such as 'oldPhoneNumber', will be removed in the future?

    1. Mark the property as 'deprecated: true' in the schema
    2. Set its type to null
    3. Delete the property immediately
    4. Move it to the top of the schema

    Explanation: Flagging the field with 'deprecated: true' formally warns consumers it is phased out. Deleting it immediately causes breaking changes; setting the type to null or reordering fields has no deprecation effect within OpenAPI.