Introduction: Why Test APIs?
Chapter 19: Test APIs with Swagger and curl
Why Testing Your API Matters
You have built a working API with FastAPI. Now you need to confirm it behaves correctly. Testing your API ensures that every endpoint returns the expected data, handles errors properly, and responds to different inputs. Without testing, you risk deploying broken code that frustrates users. In this chapter, you will learn two practical ways to test your API: using the built-in Swagger UI and using the command-line tool curl. Both methods are essential for any developer.
What You Will Learn
- How to access and use the interactive Swagger documentation
- How to test GET, POST, PUT, and DELETE endpoints with Swagger
- How to use
curlcommands to test your API from the terminal - Common mistakes when testing and how to fix them
Prerequisites
Make sure your FastAPI application from the previous lessons is running. If you stopped the server, start it again with:
uvicorn main:app --reload
Your API should be available at http://127.0.0.1:8000.
Testing with Swagger UI
FastAPI automatically generates interactive API documentation using Swagger. This is one of its most powerful features. To access it, open your browser and go to:
http://127.0.0.1:8000/docs
You will see a page listing all your endpoints. Each endpoint has a "Try it out" button. Click it to send real requests to your API and see the responses.
Step-by-Step: Test a GET Endpoint
- Open
http://127.0.0.1:8000/docsin your browser. - Find the GET /tasks/ endpoint and click on it to expand.
- Click the Try it out button.
- Click the blue Execute button.
- Look at the Response body section. You should see a list of tasks (or an empty list if you have none).
This confirms your API is working and returning data in JSON format.
Step-by-Step: Test a POST Endpoint
- In Swagger, find the POST /tasks/ endpoint and expand it.
- Click Try it out.
- In the Request body field, replace the example with a new task. For example:
{
"title": "Test Swagger",
"description": "Learning to test APIs",
"completed": false
}
- Click Execute.
- Check the Response body. You should see the created task with an
idand a201status code.
You have just created a task using Swagger. This is a quick way to test your API without writing any code.
Step-by-Step: Test PUT and DELETE
- PUT /tasks/{task_id}: Expand it, click Try it out, enter a valid task ID (e.g.,
1), modify the JSON body, and execute. You should see the updated task. - DELETE /tasks/{task_id}: Expand it, click Try it out, enter a task ID, and execute. The response should show a success message or a
204status.
Testing with curl
curl is a command-line tool that sends HTTP requests. It is widely used for testing APIs because it works in any terminal and can be automated in scripts.
Basic curl Syntax
curl -X [METHOD] [URL] -H "[HEADER]" -d "[DATA]"
-Xspecifies the HTTP method (GET, POST, PUT, DELETE).-Hadds headers, likeContent-Type: application/json.-dsends data in the request body (for POST and PUT).
Example 1: GET All Tasks
curl -X GET http://127.0.0.1:8000/tasks/
Run this in your terminal. You will see the list of tasks printed as JSON.
Example 2: POST a New Task
curl -X POST http://127.0.0.1:8000/tasks/ \
-H "Content-Type: application/json" \
-d '{"title": "curl test", "description": "Testing with curl", "completed": false}'
This sends a JSON object to create a new task. The backslash \ lets you continue the command on the next line for readability.
Example 3: GET a Single Task
curl -X GET http://127.0.0.1:8000/tasks/1
Replace 1 with the ID of the task you created.
Example 4: Update a Task (PUT)
curl -X PUT http://127.0.0.1:8000/tasks/1 \
-H "Content-Type: application/json" \
-d '{"title": "updated curl", "description": "Updated via curl", "completed": true}'
Example 5: Delete a Task
curl -X DELETE http://127.0.0.1:8000/tasks/1
Common Mistakes and How to Fix Them
- Mistake: Forgetting to include
-H "Content-Type: application/json"for POST/PUT requests.
Fix: Always add this header when sending JSON data. - Mistake: Using single quotes inside the JSON data incorrectly.
Fix: Use double quotes for JSON keys and values. On Windows, you may need to escape double quotes or use a different quoting style. - Mistake: Server not running.
Fix: Ensure your FastAPI server is running in a terminal window. - Mistake: Wrong URL or port.
Fix: Double-check the URL. The default ishttp://127.0.0.1:8000.
Why Both Methods Are Useful
Swagger UI is great for quick, visual testing and exploring your API. It is perfect for beginners and for sharing with team members who are not technical. curl is better for automation, scripting, and testing in environments without a browser. As you grow as a developer, you will use both regularly.
Practice Task
Task: Using both Swagger and curl, perform the following steps:
- Create three new tasks using Swagger.
- Use
curlto retrieve all tasks and save the output to a file namedtasks.json. - Update the second task's title to "Updated via curl" using a
curlPUT request. - Delete the first task using Swagger.
- Verify your changes by running a GET request with
curland comparing the output.
If you can complete this task, you have mastered the basics of API testing with Swagger and curl.
Loading ratings...