Why Example requests and responses in Rest API? - Purpose & Use Cases

The Big Idea

What if you could avoid all the guesswork and get APIs working right on your first try?

The Scenario

Imagine you want to get weather data from a website. Without example requests and responses, you have to guess how to ask for the data and what the reply looks like.

The Problem

Guessing leads to many mistakes. You might send wrong data or misunderstand the reply. This wastes time and causes frustration.

The Solution

Example requests and responses show exactly how to ask and what to expect back. This makes it easy to use the API correctly the first time.

Before vs After

✗ Before

POST /weather
{ "city": "" }

// What should city be? What response comes back?

✓ After

POST /weather
{ "city": "London" }

// Response: { "temp": 15, "condition": "Cloudy" }

What It Enables

Clear examples let anyone quickly understand and use an API without confusion or errors.

Real Life Example

A developer building a travel app uses example requests and responses to get accurate flight info from an airline's API.

Key Takeaways

Manual guessing wastes time and causes errors.

Examples show exactly how to ask and what to expect.

This speeds up learning and using APIs correctly.

Practice

1.

What is the main purpose of an example request in a REST API?

GET /users/123

easy

A. To list all possible API endpoints

B. To display the server's internal code

C. To describe the server's hardware

D. To show how to ask the server for specific data or action

Solution

1. Step 1: Understand what a request does

   A request is how a client asks a server for data or to perform an action.

2. Step 2: Identify the role of example requests

   Example requests show exactly how to ask the server, like which URL and method to use.

3. Final Answer:

   To show how to ask the server for specific data or action -> Option D

4. Quick Check:

   Example request = How to ask server [OK]

Hint: Example requests show how to ask the server clearly [OK]

Common Mistakes:

• Confusing requests with server code
• Thinking examples list all endpoints
• Mixing requests with server hardware info

2.

Which of the following is the correct syntax for a simple GET request example in REST API?

easy

A. GET /api/items HTTP/1.1\nHost: example.com

B. POST /api/items HTTP/1.1\nHost: example.com

C. FETCH /api/items HTTP/1.1\nHost: example.com

D. SEND /api/items HTTP/1.1\nHost: example.com

Solution

1. Step 1: Identify the HTTP method for retrieving data

   GET is the standard method to request data from a server.

2. Step 2: Check the syntax of the request line

   The correct format is "GET /path HTTP/1.1" followed by headers like Host.

3. Final Answer:

   GET /api/items HTTP/1.1\nHost: example.com -> Option A

4. Quick Check:

   GET method + correct syntax = GET /api/items HTTP/1.1\nHost: example.com [OK]

Hint: GET requests retrieve data; syntax starts with GET /path HTTP/1.1 [OK]

Common Mistakes:

• Using POST instead of GET for data retrieval
• Using non-standard methods like FETCH or SEND
• Incorrect request line format

3.

Given this example response from a REST API:

{
  "id": 101,
  "name": "Alice",
  "active": true
}

What is the value of the active field?

medium

A. false

B. true

C. "true" (string)

D. null

Solution

1. Step 1: Read the JSON response carefully

   The response shows "active": true without quotes, meaning a boolean true value.

2. Step 2: Understand JSON data types

   Boolean true is a logical value, not a string or null.

3. Final Answer:

   true -> Option B

4. Quick Check:

   Boolean true in JSON = true [OK]

Hint: True without quotes means boolean true, not string [OK]

Common Mistakes:

• Confusing boolean true with string "true"
• Choosing false or null by mistake
• Ignoring JSON syntax rules

4.

Look at this example request and response pair:

Request: POST /api/login HTTP/1.1\nHost: example.com\nContent-Type: application/json\n\n{"username": "user", "password": "pass"}

Response: 404 Not Found

What is the most likely error in the example?

medium

A. The URL path is incorrect or missing

B. The HTTP method POST is invalid

C. The Content-Type header is wrong

D. The JSON body is malformed

Solution

1. Step 1: Understand 404 Not Found meaning

   404 means the server did not find the requested URL path.

2. Step 2: Check the request details

   POST and Content-Type look correct; JSON body is valid. So the path is likely wrong or missing.

3. Final Answer:

   The URL path is incorrect or missing -> Option A

4. Quick Check:

   404 error = wrong URL path [OK]

Hint: 404 means URL path not found, check request URL [OK]

Common Mistakes:

• Thinking 404 means bad JSON or headers
• Assuming POST method is invalid
• Ignoring the URL path correctness

5.

You want to create an example response for a REST API that returns a list of products with their id and price. Which JSON response below correctly shows two products?

hard

A. [{"id": 1, "price": "9.99"}, {"id": 2, "price": "19.99"}]

B. {"id": 1, "price": 9.99, "id": 2, "price": 19.99}

C. [{"id": 1, "price": 9.99}, {"id": 2, "price": 19.99}]

D. {"products": {"id": 1, "price": 9.99}, {"id": 2, "price": 19.99}}

Solution

1. Step 1: Identify correct JSON array format

   A list of products should be an array (square brackets) containing objects for each product.

2. Step 2: Check each option's JSON structure

   [{"id": 1, "price": 9.99}, {"id": 2, "price": 19.99}] is a valid JSON array with two objects, each with id and price as numbers. {"id": 1, "price": 9.99, "id": 2, "price": 19.99} is invalid JSON with duplicate keys. [{"id": 1, "price": "9.99"}, {"id": 2, "price": "19.99"}] uses price as strings, which is allowed but less ideal. {"products": {"id": 1, "price": 9.99}, {"id": 2, "price": 19.99}} has invalid JSON syntax.

3. Final Answer:

   [{"id": 1, "price": 9.99}, {"id": 2, "price": 19.99}] -> Option C

4. Quick Check:

   Array of objects with numeric price = [{"id": 1, "price": 9.99}, {"id": 2, "price": 19.99}] [OK]

Hint: Use JSON array with objects for multiple items [OK]

Common Mistakes:

• Using duplicate keys in one object
• Incorrect JSON syntax with braces and commas
• Using strings for numeric values unnecessarily