Skip to content

postman.md

Latest commit

 

History

History
78 lines (61 loc) · 5.41 KB

postman.md

File metadata and controls

78 lines (61 loc) · 5.41 KB

🚀 Postman Master Guide & Personal Notes

1. The API Landscape: What Are We Testing?

Before making requests, it is important to understand the type of API architecture you are interacting with. Postman supports all of these:

  • REST (Representational State Transfer): The most common architecture. It relies on standard HTTP methods (GET, POST, PUT, PATCH, DELETE) to perform CRUD (Create, Read, Update, Delete) operations. You hit a specific URL endpoint, and it returns data, typically in JSON format.
  • GraphQL: Instead of hitting multiple different URLs to get different pieces of data (like REST), you hit one single endpoint (e.g., /graphql) and send a query specifying exactly the fields you want.
  • WebSockets: A persistent, bi-directional connection between the client and server. Unlike REST, where the client asks for data and the server responds once, WebSockets stay open so the server can push real-time data immediately (e.g., live chat, live notifications).
  • Socket.IO: A popular JavaScript library built on top of WebSockets. It provides reliability features, like automatically falling back to standard HTTP long-polling if a WebSocket connection drops.
  • gRPC: A high-performance framework used mostly for internal microservices communicating with each other backend-to-backend, rather than a web frontend talking to a backend. Uses Protocol Buffers instead of JSON.

2. The Anatomy of Postman: Core Components

Think of Postman as an organized laboratory. Here is how to structure your work:

Workspaces

The highest level of organization.

  • Personal Workspace: For your solo projects and local development.
  • Team Workspace: Where multiple developers share API definitions, test results, and documentation.

Collections & Folders

Collections are essentially the filing cabinets for your API requests. Never leave requests floating in the "History" tab.

  • Structure: Group related requests together. For a project, you might have a Collection named My Project APIs. Inside, create folders like Auth (Login, Register), Users (Get Profile, Update Details), and Tasks (Create Task, Delete Task).

Environments & Variables (Crucial)

Variables stop you from hardcoding values and allow you to switch contexts instantly.

  • Environment: A specific set of variables depending on where your code is running. You should have a Local environment and a Production environment.
  • Variables: Instead of typing http://localhost:8080/api/v1/users, you write {{base_url}}/api/v1/users.
    • In the Local environment, base_url = http://localhost:8080
    • In the Production environment, base_url = https://api.yourdomain.com

3. Workflows: How to Actually Use Postman

Postman goes far beyond simply pinging a server. Here are the main workflows:

A. Manual Exploration & Debugging

You are building an endpoint. You use Postman to configure the headers (e.g., Content-Type: application/json), write the JSON body, hit Send, and inspect the response status code, time, and data structure to ensure your backend logic works.

B. Request Chaining & Integration

You can use Postman scripts to pass data between requests automatically.

  • Example: When you hit a Login endpoint, your backend returns a JWT (JSON Web Token). Instead of manually copying that token, you can write a tiny script in the Tests tab of the Login request: 
    let jsonData = pm.response.json();
pm.environment.set("jwt_token", jsonData.token);
  • Now, your subsequent requests can just use {{jwt_token}} in their Authorization headers.

C. Automated Testing

In the Tests tab of any request, you can write JavaScript to assert conditions. You can run an entire Collection at once (using the Collection Runner) to test your whole backend in seconds.

  • Example Test: 
    pm.test("Status code is 200", function () {
    pm.response.to.have.status(200);
});

D. Mock Servers

If you are building a frontend but the backend APIs are not finished yet, you can create a Mock Server. You define what the JSON response should look like, and Postman gives you a temporary fake URL. The frontend can use this URL to build the UI immediately.

E. Documentation

If you organize your Collections and add markdown descriptions to your folders and requests, Postman can automatically generate clean, web-based API documentation to share with frontend developers or clients.

4. Golden Rules & Best Practices

  1. Never Hardcode Tokens or URLs: Always use {{variables}}. It saves massive amounts of time when testing locally vs. production.
  2. Inherit Auth from Parent: If all endpoints in a Tasks folder require a Bearer token, do not add the token manually to every single request.
    • Go to the folder settings.
    • Set Authorization to "Bearer Token" and paste {{jwt_token}}.
    • Ensure all requests inside the folder have their Auth set to Inherit auth from parent.
  3. Save Everything Immediately: If an endpoint works, save it, give it a descriptive name (e.g., [POST] Create New Task), and put it in the correct folder.
  4. Use Pre-request Scripts: If you need a unique timestamp or a random UUID for a request body every time you hit Send, you can generate it in the Pre-request Script tab: 
    pm.variables.set("current_timestamp", Date.now());