Testing REST APIs with Postman

# CHAPTER 27

Testing REST APIs with Postman #

1. Introduction #

When building web pages, you test your code by simply refreshing Google Chrome. But browsers are designed for GET requests; they cannot easily send POST requests, DELETE requests, custom HTTP Headers, or raw JSON bodies. To test APIs, backend developers use a specialized tool. In Chapter 27, we will explore Postman, the industry-standard software for interacting with, debugging, and automating the testing of REST APIs.

2. Learning Objectives #

By the end of this chapter, you will be able to:

• Use Postman to make GET, POST, PUT, and DELETE requests.

• Configure Headers (like Authorization) in Postman.

• Send raw JSON payloads in the request body.

• Organize API requests into Postman Collections.

• Use Postman Environment Variables to switch between Local and Production URLs.

3. Beginner-Friendly Explanation #

Think of Postman as a web browser specifically designed for developers. Instead of an address bar and a white screen, Postman gives you a massive control panel. You can select the exact HTTP method from a dropdown, type in the URL, attach a VIP pass (Authorization Token) in the Headers tab, write a letter (JSON) in the Body tab, and press "Send." Postman then displays the server's exact response—headers, status codes, and formatted JSON data—making debugging incredibly easy.

4. Real-World Examples #

• Debugging: You wrote a PHP script for POST /users, but it isn't working. Instead of writing a frontend HTML form just to test it, you open Postman, type some JSON, and hit Send to see the exact PHP error.

• Sharing: A backend developer creates a complete "Collection" (a folder of saved requests) in Postman and emails it to the frontend team. The frontend team imports it and instantly knows how to call every endpoint.

5. Detailed Code Examples #

Let's see how you configure Postman to test a secure endpoint.

Scenario: We want to test POST /api/articles

1. 1. Open Postman.

1. 2. Change the method dropdown from GET to POST.

1. 3. Enter URL: http://localhost/api/articles.

1. 4. Go to the Authorization tab.

• Select Type: Bearer Token

• Paste your token: eyJhbGciOi...

1. 5. Go to the Body tab.

• Select raw

• Change the text format dropdown from Text to JSON

• Enter your payload:

``json { "title": "Learning Postman", "content": "Postman is awesome." } `

1. 6. Click Send.

1. 7. View the formatted JSON output and the 201 Created status code at the bottom.

6. Request/Response Examples #

Postman beautifully formats the response. If you make a mistake (e.g., forgetting a comma in your JSON body), your PHP API (from Chapter 18) will return a 400 Bad Request. Postman clearly highlights the red 400 status code, saving you hours of guessing why the request failed.

7. HTTP Examples #

Postman allows you to inspect the hidden HTTP data. By clicking the "Console" button at the bottom of Postman, you can see the raw HTTP request exactly as it left your computer, including every single header Postman generated automatically.

8. JSON Examples #

When dealing with file uploads (Chapter 22), you cannot use the raw JSON body. Instead, in the Body tab, you select form-data. You type a key (e.g., avatar), hover over the key to change its type from "Text" to "File", and then Postman gives you a button to select an image from your computer.

9. Best Practices #

• Use Collections: Never leave your Postman workspace cluttered with unsaved tabs. Create a "Collection" named after your project, and save every endpoint into folders (e.g., "Users", "Products").

• Use Environment Variables: Never hardcode http://localhost into your Postman URLs. Use a variable: {{base_url}}/users. Then, create a "Local" environment where base_url is localhost, and a "Production" environment where base_url is https://api.mywebsite.com. You can switch environments with one click!

10. Common Mistakes #

• Sending JSON as Text: In the Body tab, beginners often select raw but forget to change the dropdown to JSON. Postman defaults to Text. If left as Text, Postman won't send the Content-Type: application/json header, and your PHP $_POST / php://input logic will fail.

• Forgetting to save: Postman tabs are temporary. If you spend 10 minutes perfectly configuring a complex POST request with headers and auth tokens, click the "Save" button to add it to a Collection.

11. Mini Exercises #

1. 1. Download Postman (or use the web version).

1. 2. Create a new GET request to https://jsonplaceholder.typicode.com/users/1.

1. 3. Click Send and inspect the JSON response.

12. Coding Challenges #

Challenge 1: In Postman, configure a POST request to https://httpbin.org/post. Add a custom header X-My-Header: Hello and a JSON body {"test": 123}. Send it, and read the response to verify httpbin received your header and body.

13. MCQs with Answers #

Question 1

Why do developers use Postman instead of a standard web browser like Chrome to test APIs?

A Browsers cannot display JSON. B Browsers cannot easily send POST/PUT/DELETE requests or custom headers without writing custom JavaScript/HTML. C Postman encrypts the code.

Check Answer

Question 2

When sending JSON in Postman, which Body option must you select?

A form-data B x-www-form-urlencoded C raw (with JSON selected from the dropdown)

Check Answer

Question 3

What is a Postman "Collection"?

A A database built into Postman. B A folder system used to group, save, and share API requests. C A collection of JSON parsing scripts.

Check Answer

14. Interview Questions #

• Q: Walk me through the exact steps to test an authenticated POST request with a JSON payload using Postman.

• Q: What are Postman Environment Variables and why are they crucial for professional API development?

• Q: How do you test a file upload endpoint (multipart/form-data`) in Postman?

15. FAQs #

Q: Is Postman the only tool available? A: No. Insomnia is a very popular, lightweight alternative. Some developers also prefer testing directly in VS Code using extensions like "Thunder Client" or "REST Client". However, Postman remains the industry heavyweight.

16. Summary #

In Chapter 27, we explored Postman, the ultimate tool for API developers. We learned how to craft precise HTTP requests, send JSON payloads, attach Bearer tokens, and simulate file uploads. We also highlighted the importance of organizing requests into Collections and using Environment Variables to switch seamlessly between local development and live production servers.

17. Next Chapter Recommendation #

Our API is built, documented, and tested. But is it fast enough for production? Proceed to Chapter 28: REST API Performance Optimization to learn how to speed up your endpoints using caching and compression.