Request and Response Structure

# CHAPTER 8

Request and Response Structure #

1. Introduction #

2. Learning Objectives #

• Identify common Request headers sent by clients.

• Identify common Response headers sent by servers.

• Understand the critical role of the Content-Type header.

• Explain "Content Negotiation" using the Accept header.

• Build a PHP script that reads and sets headers programmatically.

3. Beginner-Friendly Explanation #

• If you hand the waiter a menu order written in Spanish, you should tell them, "Hey, this is written in Spanish." (This is the Content-Type header).

• Before you order, you might tell the waiter, "I only understand English, so please reply to me in English." (This is the Accept header).

Headers are simply invisible metadata instructions that travel along with your data, ensuring that the machine on the other end knows exactly how to read and respond to your request.

4. Real-World Examples #

• File Uploads: When you upload an image via an API, your client sets Content-Type: multipart/form-data. This tells the server, "Hey, I am not sending you a simple text string; I am sending a heavy binary file."

• API Versioning: Some companies put their API version in a header instead of the URL, sending Accept-Version: v2 to ask the server for the newest format of the data.

5. Detailed Code Examples #

<?php
// A simple API that can speak both JSON and XML
$headers = getallheaders();
$accept = isset($headers[&#039;Accept']) ? $headers['Accept'] : 'application/json';

$data = ["id" => 1, "name" => "John"];

if (strpos($accept, &#039;application/xml') !== false) {
    // Client requested XML
    header("Content-Type: application/xml");
    echo "<?xml version=\"1.0\"?><user><id>1</id><name>John</name></user>";
} else {
    // Default to JSON
    header("Content-Type: application/json");
    echo json_encode($data);
}
?>

6. Request/Response Examples #

Request Structure:

POST /api/products HTTP/1.1
Host: api.store.com
Authorization: Bearer mySecretToken123
Accept: application/json
Content-Type: application/json
User-Agent: PostmanRuntime/7.28.0

{"name": "Laptop", "price": 1200}

Response Structure:

HTTP/1.1 201 Created
Date: Wed, 12 Oct 2026 10:00:00 GMT
Server: Nginx/1.18.0
Content-Type: application/json
X-RateLimit-Remaining: 99
Content-Length: 42

{"success": true, "product_id": 405}

7. HTTP Examples #

• application/json (Standard REST API data)

• application/xml (Older APIs, SOAP)

• application/x-www-form-urlencoded (Standard HTML forms)

• multipart/form-data (File uploads)

8. JSON Examples #

HTTP/1.1 200 OK
Content-Type: application/json
X-Total-Count: 1500
X-Total-Pages: 15

[
  {"id": 1, "name": "Item 1"},
  {"id": 2, "name": "Item 2"}
]

*Note: We put the total count in the header (X-Total-Count) so the JSON body can just be a clean array.*

9. Best Practices #

• Always Validate Content-Type: If your API expects JSON, verify that the request's Content-Type is application/json. If it's not, return a 415 Unsupported Media Type status code.

• Set the Response Content-Type: If you are echoing JSON in PHP, you *must* include header('Content-Type: application/json');. If you forget, the browser might assume it's just raw HTML or plain text, causing parsing errors on the client side.

10. Common Mistakes #

• Relying on $POST for JSON: In PHP, the $POST superglobal *only* works automatically if the client sends application/x-www-form-urlencoded or multipart/form-data. If the client sends application/json, $POST will be completely empty! You must read JSON manually using filegetcontents('php://input').

1. 2. Review the PHP phpinfo() function in a test script and look for the HTTPACCEPT and CONTENTTYPE server variables.

• Q: Why is $POST empty in PHP when a client sends a standard JSON API payload? How do you fix it?

• Q: What is the purpose of custom headers (like X-RateLimit-Remaining), and when should you use them instead of putting the data in the JSON body?

15. FAQs #

Q: What does the User-Agent header do? A: It tells the server what software the client is using (e.g., Chrome, Safari, Postman, or a custom Python script). Servers often log this for analytics or debugging.

16. Summary #

17. Next Chapter Recommendation #