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).

Practice

1. What is the main purpose of endpoint documentation in a REST API?

easy

A. To explain how to use each API URL including methods and parameters

B. To store user data securely

C. To improve the speed of the API server

D. To design the user interface of a website

Solution

1. Step 1: Understand the role of endpoint documentation

   Endpoint documentation describes how to use each API URL, including methods and parameters.

2. Step 2: Compare options with this role

   Only To explain how to use each API URL including methods and parameters matches this purpose; others describe unrelated tasks.

3. Final Answer:

   To explain how to use each API URL including methods and parameters -> Option A

4. Quick Check:

   Endpoint documentation = Usage guide [OK]

Hint: Think: What helps users understand API URLs? [OK]

Common Mistakes:

• Confusing documentation with data storage
• Mixing API documentation with UI design
• Assuming documentation improves server speed

2. Which of the following is the correct way to document the HTTP method in an endpoint documentation?

easy

A. "method": "GET"

B. "method" = GET

C. method: GET;

D. GET

Solution

1. Step 1: Identify proper JSON syntax for documentation

   Endpoint docs often use JSON or similar formats; key-value pairs use colon and quotes for strings.

2. Step 2: Check each option's syntax

   "method": "GET" uses correct JSON syntax with quotes and colon; others use invalid or non-standard syntax.

3. Final Answer:

   "method": "GET" -> Option A

4. Quick Check:

   JSON key-value = colon + quotes [OK]

Hint: Remember JSON syntax: key in quotes, colon, value in quotes [OK]

Common Mistakes:

• Using equal sign instead of colon
• Omitting quotes around strings
• Using XML tags instead of JSON

3. Given this endpoint documentation snippet:

{
  "endpoint": "/users/{id}",
  "method": "GET",
  "parameters": {
    "id": "integer"
  },
  "response": {
    "200": "User object",
    "404": "Not Found"
  }
}

What is the expected response if the user ID does not exist?

medium

A. User object with empty fields

B. 404 Not Found error

C. 200 OK with error message

D. 500 Internal Server Error

Solution

1. Step 1: Read the response codes in the documentation

   The response section shows "404": "Not Found" which means if the user ID is missing, a 404 error is returned.

2. Step 2: Match the scenario to the response code

   Since the user ID does not exist, the API returns 404 Not Found, not 200 or 500.

3. Final Answer:

   404 Not Found error -> Option B

4. Quick Check:

   Missing resource = 404 Not Found [OK]

Hint: 404 means resource not found, check response codes [OK]

Common Mistakes:

• Assuming 200 OK always returns
• Confusing 404 with 500 server error
• Expecting empty user object instead of error

4. You see this endpoint documentation snippet:

{
  "endpoint": "/items",
  "method": "POST",
  "parameters": {
    "name": "string",
    "quantity": "integer"
  },
  "response": {
    "201": "Item created"
  }
}

But the API returns a 400 error when you send the request. What is the most likely mistake in the documentation?

medium

A. The endpoint URL is missing a trailing slash

B. The HTTP method should be GET, not POST

C. Parameters should be inside a "requestBody" section, not "parameters"

D. The response code 201 is incorrect for creation

Solution

1. Step 1: Understand POST request structure

   POST requests usually send data in the request body, not as URL parameters.

2. Step 2: Check documentation structure

   Parameters listed under "parameters" implies URL/query parameters; for POST data, it should be under "requestBody".

3. Final Answer:

   Parameters should be inside a "requestBody" section, not "parameters" -> Option C

4. Quick Check:

   POST data = requestBody, not parameters [OK]

Hint: POST data goes in requestBody, not parameters [OK]

Common Mistakes:

• Confusing query parameters with request body
• Changing HTTP method incorrectly
• Ignoring correct response codes

5. You want to document an endpoint that updates a user's email. It uses PATCH method at /users/{id}. The request body must include email as a string. The response returns 200 with updated user data or 400 if email is invalid. Which is the best way to structure this documentation snippet?

hard

A. {
"endpoint": "/users/{id}",
"method": "PATCH",
"parameters": {
"id": "integer",
"email": "string"
},
"response": {
"200": "Updated user object",
"400": "Invalid email error"
}
}

B. {
"endpoint": "/users",
"method": "PATCH",
"parameters": {
"email": "string"
},
"response": {
"200": "Updated user object",
"400": "Invalid email error"
}
}

C. {
"endpoint": "/users/{id}",
"method": "POST",
"parameters": {
"id": "integer",
"email": "string"
},
"response": {
"200": "Updated user object",
"400": "Invalid email error"
}
}

D. {
"endpoint": "/users/{id}",
"method": "PATCH",
"parameters": {
"id": "integer"
},
"requestBody": {
"email": "string"
},
"response": {
"200": "Updated user object",
"400": "Invalid email error"
}
}

Solution

1. Step 1: Identify correct HTTP method and endpoint

   The method is PATCH and endpoint includes user ID as a path parameter "/users/{id}".

2. Step 2: Separate path parameters and request body

   "id" is a path parameter, so it goes under "parameters"; "email" is sent in request body, so it belongs in "requestBody".

3. Step 3: Check response codes and descriptions

   Response codes 200 and 400 with correct descriptions match the scenario.

4. Final Answer:

   { "endpoint": "/users/{id}", "method": "PATCH", "parameters": { "id": "integer" }, "requestBody": { "email": "string" }, "response": { "200": "Updated user object", "400": "Invalid email error" } } -> Option D

5. Quick Check:

   Path params + requestBody + responses = { "endpoint": "/users/{id}", "method": "PATCH", "parameters": { "id": "integer" }, "requestBody": { "email": "string" }, "response": { "200": "Updated user object", "400": "Invalid email error" } } [OK]

Hint: Put path params in parameters, data in requestBody [OK]

Common Mistakes:

• Putting request body fields in parameters
• Using wrong HTTP method
• Omitting requestBody section