First requests in Postman

What you will be able to do

Work with an API the way many teams do every day: in Postman. There, each request is saved, easy to change and easy to send again. You start from your API’s own OpenAPI document, so every endpoint is ready in one step.

Before you startWhat to know and to have readyAbout 40 minutes

What you need to know

• Your contract table and its failure rows, from Resource and endpoint design: Rule 4: write the contract as a table and Validation and error responses: Worked example: every error, one shape.
• Where the title, tags and summaries in /openapi.json come from, from Documentation people can use: Where each part of the documentation comes from.

What you need on your computer

• The API runs locally with fastapi dev, and http://127.0.0.1:8000/openapi.json opens, as at the end of Keep the documentation true: Guided practice: protect the contract. If you started it with SHOW_DOCS=false, start it again without the variable.
• If you added explanation in that lesson’s “Your turn” task, remove it and export the contract again, as the task says.
• A free Postman account. The Postman app needs one to keep collections and environments. The Free plan is for one person, and needs no payment. If you do not want an account, you can follow this module with Swagger UI and curl. The Postman CLI in lesson 3 works without one.
• About 500 MB of disk space for the app.
• If your project is missing or broken, copy the snapshot end-of-m04, the project at the end of Module 4. Use a snapshot has the steps.

The steps for the app follow Postman’s documentation for Postman 12. The Postman team changes the app often, so a button can have a slightly different name or place.

Why another tool?

You can already send requests with curl and Swagger UI. Each has limits:

Tool	Good for	Not good for
curl	One request, a script, a bug report	Many requests, long bodies, comparing responses
Swagger UI	Trying the endpoints of one API, from its documentation	Saving requests, many environments, tests
Postman	Keeping every request that you work with, with names, variables and tests, for several APIs and environments	Automated tests inside the code (that is pytest’s job)

Postman is an API client: an app to build, send, save and test requests. Requests are kept in collections: named groups of requests, in folders, that you can share, run and export. Many companies give their partners a Postman collection with their API, next to the OpenAPI document.

Install the app and sign in

1. Go to postman.com/downloads, and download the desktop app for your system.
2. Install it, and open it.
3. Sign in with your Postman account, or select the option to create a free account.
4. Use the desktop app for this course, not Postman in a web browser. The web version cannot reach 127.0.0.1 on your computer without an extra program, the Postman Desktop Agent.

Worked example: a first request

Amira’s API is running on http://127.0.0.1:8000. In Postman, she opens a new request tab (the + next to the open tabs), and:

1. Leaves the method as GET, and types the URL http://127.0.0.1:8000/health.
2. Selects Send.

The response appears in the lower half of the window:

Part of the response pane	Shows
The status line	200 OK, the time in milliseconds, and the size
Body	{"status": "ok"}, formatted (Pretty) or as received (Raw)
Headers	The response headers, such as content-type: application/json

Then a POST with a JSON body:

1. In a new tab, choose the method POST, and type http://127.0.0.1:8000/v1/classify.

2. Open the Body tab of the request. Select raw, then JSON in the list next to it.

3. Type the body:

   {
     "subject": "Charged twice for March",
     "body": "My card was charged two times for the same invoice."
   }

4. Select Send. The response is 200 OK with "category": "billing" and "priority": 1.

When you choose JSON, Postman adds the header Content-Type: application/json for you. You can see it in the request’s Headers tab, among the headers that Postman adds automatically.

Import the OpenAPI document

Typing each request by hand is slow, and it repeats work: your API already describes every endpoint in /openapi.json. Postman can make a collection from it.

1. Select Import (near the top left of the app).
2. Paste the URL http://127.0.0.1:8000/openapi.json.
3. Postman recognises an OpenAPI document. Choose Postman Collection.
4. Select View Import Settings. Set Folder organization to Tags, so the folders match the sections in Swagger UI.
5. Select Import. A collection called Ticket Classifier API appears in the sidebar.

Open it. The import used the documentation that you wrote in Module 4:

In Postman	Comes from
The collection name, Ticket Classifier API	title in FastAPI(...)
The folders tickets and health	The tags
The request names, such as Classify a support ticket	The summary of each route
The description of each request	The description of each route
The saved examples under each request	The documented responses, such as 422 with the error shape

Good summaries in the code now give good names in Postman.

Make the imported requests work

Two things still need your attention.

The base URL. Open Classify a support ticket. Its URL is {{baseUrl}}/v1/classify. {{baseUrl}} is a variable: Postman replaces it with a value before it sends the request. The import made it a variable of the collection, with the value /, because the OpenAPI document does not say where the API runs. Set it:

1. Select the collection in the sidebar, and open its Variables tab.
2. Set the value of baseUrl to http://127.0.0.1:8000 (no / at the end).
3. Save the collection (Ctrl+S, or Cmd+S on macOS).

The request body. The import filled the body from the schema, not from your example: "subject": "<string>". That is a valid string, and it returns other. Replace it with a real ticket, and save the request. Postman does not save a change to a request until you save it: an unsaved tab shows a dot in its name.

Now send List the ticket categories and Classify a support ticket. Both return 200.

From Postman to curl, and back

A Postman request is easy to share as a curl command, for example in a bug report. Open a request, and select the Code icon (</>) on the right. Choose cURL. Postman shows the command, with the variable already replaced by its value.

It also works the other way. Paste a curl command into the URL field, and Postman makes a request from it, with the method, headers and body.

Guided practice: your workspace

1. Install Postman, sign in, and open a new request tab.
2. Send GET http://127.0.0.1:8000/health. Find the status, the time and the content-type header in the response pane.
3. Import http://127.0.0.1:8000/openapi.json as a Postman Collection, with folders by tags.
4. Set the collection variable baseUrl to http://127.0.0.1:8000, and save the collection.
5. Open Classify a support ticket, put a real ticket in the body, save it, and send it.
6. Open the saved examples under the request. Find the example for 422, and compare it with the error shape from Module 3.
7. Open the Code view, and copy the request as cURL. Run the command in a terminal. (On Windows, change it to use a body file, as in Module 1.)

Your turn: requests for every row

Your contract table from Module 3 has failure rows. In the collection’s tickets folder, make one saved request for each of these, with a name that says what it checks:

1. Reject an empty subject: {"subject": ""}.
2. Reject an unknown field: {"subject": "Refund", "colour": "red"}.
3. Reject a GET on classify: GET {{baseUrl}}/v1/classify.

To make a copy of a request, use Duplicate in its menu (the … next to its name). Send each one, and check the status code and the fields against the table.

Show what you should see

1. 422, "code": "invalid_request", "fields": ["subject"].
2. 422, "fields": ["colour"], because TicketIn forbids extra fields.
3. 405, "code": "method_not_allowed".

In lesson 3, you add tests to these requests, so Postman checks the results for you.

Common mistake

Could not send request: ECONNREFUSED

Symptom: Postman shows Could not send request and Error: connect ECONNREFUSED 127.0.0.1:8000, or the web version of Postman cannot reach your local API.

Cause: nothing listens on that address and port. Usually, the API is not running, or it runs on a different port. With Postman in a web browser, the request comes from Postman’s servers or your browser, not from your computer’s terminal. So it cannot reach 127.0.0.1 without the Desktop Agent.

Fix:

1. Check the API’s terminal: fastapi dev must be running, and say Uvicorn running on http://127.0.0.1:8000.
2. Check baseUrl: the scheme (http, not https), the host and the port.
3. Use the desktop app for local APIs.

Check your understanding

After the import, a request's URL is {{baseUrl}}/v1/classify, and sending it fails with an invalid URL. Why, and where do you fix it?

Show the answer

{{baseUrl}} is a variable, and the import set it to /, because the OpenAPI document does not say where the API runs. So the URL becomes //v1/classify. Set baseUrl to http://127.0.0.1:8000 in the collection’s Variables tab. In the next lesson, a Postman environment holds it instead, so that one collection works for the local and the deployed API.

Recap

• Postman is an API client that keeps requests in collections, with names, folders and saved examples.
• Use the desktop app for an API on your computer.
• Importing /openapi.json makes a collection from your documentation: tags become folders, and summaries become request names.
• {{baseUrl}} is a variable. Set its value, and replace the generated <string> bodies with real ones.
• The Code view turns a request into a curl command.

Next, you make the collection work for more than one environment, and keep secrets out of it.

Next: Collections, variables and environments