Test APIs with Swagger and curl

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 curl commands 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

1. Open http://127.0.0.1:8000/docs in your browser.
2. Find the GET /tasks/ endpoint and click on it to expand.
3. Click the Try it out button.
4. Click the blue Execute button.
5. 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

1. In Swagger, find the POST /tasks/ endpoint and expand it.
2. Click Try it out.
3. In the Request body field, replace the example with a new task. For example:

{
  "title": "Test Swagger",
  "description": "Learning to test APIs",
  "completed": false
}

4. Click Execute.
5. Check the Response body. You should see the created task with an id and a 201 status 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 204 status.

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]"

• -X specifies the HTTP method (GET, POST, PUT, DELETE).
• -H adds headers, like Content-Type: application/json.
• -d sends 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 is http://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