OpenAPI has become a crucial standard for defining and documenting APIs, enabling seamless integration and communication between different software systems. By providing a clear and structured format for API specifications, OpenAPI helps developers create, maintain, and consume APIs more efficiently. Its widespread adoption across various industries underscores its importance in modern software development.
This guide offers a curated selection of OpenAPI interview questions designed to test your understanding and proficiency with the specification. Reviewing these questions will help you demonstrate your expertise and readiness to tackle real-world challenges involving API design and implementation.
OpenAPI Interview Questions and Answers
1. Write a simple OpenAPI definition for a GET /users endpoint that returns a list of users.
An OpenAPI definition for a GET /users endpoint can be written in YAML format. This includes the openapi version, info section, paths, and components. The paths section defines the GET /users endpoint, and the components section defines the User schema.
openapi: 3.0.0
info:
title: User API
version: 1.0.0
paths:
/users:
get:
summary: Get list of users
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
components:
schemas:
User:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: John Doe
email:
type: string
example: [email protected]
2. How do you define query parameters in an OpenAPI specification? Provide an example.
In OpenAPI, query parameters are used to pass data to the server as part of the URL. They are defined within the parameters section and specified as being of type “query”.
Example:
openapi: 3.0.0
info:
title: Sample API
version: 1.0.0
paths:
/items:
get:
summary: Retrieve a list of items
parameters:
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 100
required: false
description: The number of items to return
- in: query
name: sort
schema:
type: string
enum: [asc, desc]
required: false
description: The sort order of the items
responses:
'200':
description: A list of items
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
3. Write an OpenAPI definition for an endpoint that accepts a JSON body with user details and returns a success message.
openapi: 3.0.0
info:
title: User API
version: 1.0.0
paths:
/user:
post:
summary: Create a new user
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
email:
type: string
age:
type: integer
required:
- name
4. How can you document authentication mechanisms in OpenAPI? Provide an example.
Documenting authentication mechanisms in OpenAPI involves specifying the security schemes and applying them to the API operations.
Example:
openapi: 3.0.0
info:
title: Sample API
version: 1.0.0
paths:
/users:
get:
summary: Get user list
security:
- bearerAuth: []
responses:
'200':
description: A list of users
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
In this example, the components section defines a security scheme named bearerAuth using the HTTP bearer token mechanism. The paths section applies this security scheme to the /users endpoint, indicating that a bearer token is required to access this resource.
5. Describe how to use $ref to reference reusable components in OpenAPI.
In OpenAPI, the $ref keyword is used to reference reusable components, such as schemas, responses, parameters, and examples. This promotes reuse and avoids duplication. The $ref keyword points to a specific location within the OpenAPI document or an external file.
Example:
openapi: 3.0.0
info:
title: Sample API
version: 1.0.0
paths:
/users:
get:
summary: Get a list of users
responses:
'200':
description: A JSON array of user names
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
components:
schemas:
UserList:
type: array
items:
type: string
In this example, the $ref keyword is used to reference the UserList schema defined under the components section.
6. Write an OpenAPI definition for an endpoint that uses path parameters.
Path parameters are used in OpenAPI to capture variable parts of the URL path, enabling dynamic routing based on the URL.
Here is an example of an OpenAPI definition for an endpoint that uses path parameters:
openapi: 3.0.0
info:
title: Sample API
version: 1.0.0
paths:
/users/{userId}:
get:
summary: Get user by ID
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
id:
type: string
name:
type: string
'404':
description: User not found
7. How do you handle different response codes in an OpenAPI specification? Provide an example.
Different response codes are handled by defining them in the responses section of an operation object. Each response code can have a description and a schema that describes the structure of the response body.
Example:
paths:
/users:
get:
summary: Retrieve a list of users
responses:
'200':
description: A list of users
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
name:
type: string
'400':
description: Bad Request
'401':
description: Unauthorized
'500':
description: Internal Server Error
In this example, the GET /users endpoint has multiple response codes defined. A 200 response indicates a successful retrieval of users, with the response body being an array of user objects. Other response codes like 400, 401, and 500 are also defined to handle various error conditions.
8. Write an OpenAPI definition for an endpoint that supports both JSON and XML response formats.
openapi: 3.0.0
info:
title: Sample API
version: 1.0.0
paths:
/example:
get:
summary: Example endpoint
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: "This is a JSON response"
application/xml:
schema:
type: object
properties:
message:
type: string
example: "This is an XML response"
9. How do you define security schemes in OpenAPI?
Security schemes in OpenAPI define the authentication and authorization mechanisms for an API. These schemes specify how the API should handle security, including the types of authentication supported.
Example:
openapi: 3.0.0
info:
title: Sample API
version: 1.0.0
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
OAuth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://example.com/oauth/authorize
tokenUrl: https://example.com/oauth/token
scopes:
read: Grants read access
write: Grants write access
security:
- ApiKeyAuth: []
- OAuth2:
- read
- write
paths:
/example:
get:
security:
- ApiKeyAuth: []
responses:
'200':
description: Successful response
In this example, two security schemes are defined: ApiKeyAuth and OAuth2. The ApiKeyAuth scheme specifies that an API key should be passed in the header with the name X-API-Key. The OAuth2 scheme defines an OAuth2 authorization code flow with specific authorization and token URLs, as well as scopes for read and write access. The security section at the root level applies these schemes globally, while the security section within the /example path applies the ApiKeyAuth scheme specifically to the GET operation.
10. Write an OpenAPI definition for an endpoint that includes a multipart/form-data request body for file uploads.
openapi: 3.0.0
info:
title: File Upload API
version: 1.0.0
paths:
/upload:
post:
summary: Upload a file
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
responses:
'200':
description: File uploaded successfully
'400':
description: Bad request