Endpoint documentation structure in Rest API - Practice Problems & Coding Challenges

Challenge - 5 Problems

❓ Predict Output

intermediate

What is the output of this OpenAPI snippet?

Given this OpenAPI endpoint documentation snippet, what is the value of the summary field for the GET method?

Rest API

{
  "paths": {
    "/users": {
      "get": {
        "summary": "Retrieve list of users",
        "responses": {
          "200": {
            "description": "A JSON array of user names"
          }
        }
      }
    }
  }
}

A Retrieve list of users

B List all users

C GET /users endpoint

D A JSON array of user names

💡 Hint

Look for the summary key inside the GET method object.

The summary field describes the purpose of the endpoint method. Here, it is "Retrieve list of users".

🧠 Conceptual

intermediate

Which field describes the expected response status code in REST API docs?

In REST API endpoint documentation, which field typically specifies the HTTP status code returned by the server?

A responses

B parameters

C requestBody

D summary

💡 Hint

Think about where the server tells what it sends back.

The responses field contains HTTP status codes and descriptions of the server's replies.

🔧 Debug

advanced

Identify the error in this endpoint documentation snippet

What error will this OpenAPI snippet cause when validating the documentation?

Rest API

{
  "paths": {
    "/items/{itemId}": {
      "get": {
        "parameters": [
          {
            "name": "itemId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Item details"
          }
        }
      }
    }
  }
}

A Schema type should be 'integer' not 'string'

B Missing response status code 404 for not found

C Parameter location should be 'path' not 'query' for path variables

D Parameters array should be empty for GET requests

💡 Hint

Check the in field for the path parameter.

Path parameters must have in set to "path". Using "query" for a path variable is invalid.

📝 Syntax

advanced

Which option is the correct syntax for defining a POST request body in OpenAPI?

Select the correct JSON snippet that defines a POST request body with a JSON schema for a user object.

A "body": {"content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}}}}}}

B "requestBody": {"content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string"}}}}}}

C "requestBody": {"schema": {"type": "object", "properties": {"name": {"type": "string"}}}}

D "requestBody": {"content": {"application/xml": {"schema": {"type": "object", "properties": {"name": {"type": "string"}}}}}}

💡 Hint

Look for the correct key names and content type for JSON.

The requestBody field must include content with the media type application/json and a schema describing the data.

🚀 Application

expert

How many parameters are defined in this endpoint documentation?

Count the total number of parameters defined for this endpoint, including path, query, and header parameters.

Rest API

{
  "paths": {
    "/search": {
      "get": {
        "parameters": [
          {"name": "q", "in": "query", "required": true, "schema": {"type": "string"}},
          {"name": "limit", "in": "query", "schema": {"type": "integer"}},
          {"name": "Authorization", "in": "header", "required": true, "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {"description": "Search results"}
        }
      }
    }
  }
}

A 2

B 1

C 4

D 3

💡 Hint

Count all items inside the parameters array.

There are three parameters: 'q' (query), 'limit' (query), and 'Authorization' (header).