APIs are the backbone of most applications that rely on data exchange or external integrations.
Learning to build APIs in Python can open up many opportunities to connect your app with other systems and make a versatile backend.
Here, I’ll walk you through the basics of APIs, creating REST APIs, and building them with Flask and FastAPI—two popular Python frameworks.
1. Introduction to APIs
In today’s digital world, APIs are everywhere.
They allow different systems and applications to talk to each other, sharing data and functionalities seamlessly.
For example, when you use an app to check the weather, it's actually calling an API that returns the weather data.
APIs make life easier by acting as intermediaries that process requests and return data in a standardized way.
It’s also worth noting that APIs don’t only serve client applications (like websites or mobile apps).
APIs can be used between backend systems or microservices within the same infrastructure to manage data more efficiently.
2. REST APIs
REST (Representational State Transfer) is one of the most popular ways to create APIs due to its simplicity and compatibility with HTTP.
RESTful APIs are structured to allow standard HTTP methods (like GET, POST, PUT, DELETE) to manipulate resources.
They’re often used to manage CRUD (Create, Read, Update, and Delete) operations, where each request method performs an operation on the resource data.
If you're building a web service, REST is likely the most approachable and widely supported format to start with.
REST APIs are also stateless, which means each request operates independently, allowing REST APIs to scale more easily.
Excited to dive deeper into the world of Python programming?
Look no further than my latest ebook, "Python Tricks - A Collection of Tips and Techniques".
Get the eBook
Inside, you'll discover a collection of Python secrets that will guide you through a journey of learning how to write cleaner, faster, and more Pythonic code.
3. Building an API with Flask
Flask is my go-to for small or medium-sized projects, as it’s lightweight and easy to get up and running.
Flask lets you control nearly every aspect of your API, but it also requires a bit more work on data validation and error handling.
This flexibility, though, is ideal for those who want more control over how each part of the API functions.
Example of Creating a Flask API
Here’s how a task management API can look in Flask.
First, make sure to install flask with pip:
pip install flaskThis example shows how you can quickly set up endpoints for getting and creating tasks, as well as updating and deleting.
from flask import Flask, jsonify, request
app = Flask(__name__)
tasks = [
{"id": 1, "task": "Learn Flask", "done": False},
{"id": 2, "task": "Build API", "done": False}
]
@app.route('/tasks', methods=['GET'])
def get_tasks():
return jsonify({"tasks": tasks})
@app.route('/tasks', methods=['POST'])
def create_task():
new_task = {
"id": len(tasks) + 1,
"task": request.json["task"],
"done": False
}
tasks.append(new_task)
return jsonify(new_task), 201
@app.route('/tasks/<int:task_id>', methods=['GET'])
def get_task(task_id):
task = next((task for task in tasks if task["id"] == task_id), None)
if task:
return jsonify(task)
return jsonify({"message": "Task not found"}), 404
@app.route('/tasks/<int:task_id>', methods=['PUT'])
def update_task(task_id):
task = next((task for task in tasks if task["id"] == task_id), None)
if task:
task.update(request.json)
return jsonify(task)
return jsonify({"message": "Task not found"}), 404
@app.route('/tasks/<int:task_id>', methods=['DELETE'])
def delete_task(task_id):
task = next((task for task in tasks if task["id"] == task_id), None)
if task:
tasks.remove(task)
return jsonify({"message": "Task deleted"})
return jsonify({"message": "Task not found"}), 404
if __name__ == '__main__':
app.run(debug=True)
This Python code sets up a REST API using Flask to manage a list of tasks, allowing clients to create, retrieve, update, and delete tasks.
The tasks are stored in a list where each task is a dictionary with an id, task, and done status.
The /tasks endpoint supports GET requests to return the full list of tasks and POST requests to add new tasks, automatically assigning each task a unique ID.
Additional endpoints, /tasks/<int:task_id>, allow users to interact with individual tasks: GET retrieves a specific task by ID, PUT updates it, and DELETE removes it from the list.
If a task with the specified ID is not found, these endpoints return a 404 error with an appropriate message.
The API runs in debug mode, making it ideal for development and testing purposes.
Just be aware that for larger projects, you might need to add more structured routing and validation mechanisms.
4. Building an API with FastAPI
FastAPI is an excellent choice for performance-sensitive applications or projects that require a bit more structure and type safety.
FastAPI is designed to be faster by default (thanks to its asynchronous capabilities) and offers robust data validation out-of-the-box using Pydantic.
I’ve found FastAPI very intuitive and easy to work with, especially for projects where I need async capabilities and want built-in validation without third-party packages.
Plus, the automatic documentation (via Swagger UI) makes it extremely convenient.
Example of Creating a FastAPI API
Here’s how the task management API could look in FastAPI.
Don't forget to first install fastapi and uvicorn with pip:
pip install fastapi uvicornThen you can create the API:
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List
app = FastAPI()
class Task(BaseModel):
id: int
task: str
done: bool = False
tasks: List[Task] = [
Task(id=1, task="Learn FastAPI", done=False),
Task(id=2, task="Build API", done=False)
]
@app.get("/tasks", response_model=List[Task])
def get_tasks():
return tasks
@app.post("/tasks", response_model=Task)
def create_task(task: Task):
tasks.append(task)
return task
@app.get("/tasks/{task_id}", response_model=Task)
def get_task(task_id: int):
task = next((task for task in tasks if task.id == task_id), None)
if task:
return task
raise HTTPException(status_code=404, detail="Task not found")
@app.put("/tasks/{task_id}", response_model=Task)
def update_task(task_id: int, task: Task):
for t in tasks:
if t.id == task_id:
t.task = task.task
t.done = task.done
return t
raise HTTPException(status_code=404, detail="Task not found")
@app.delete("/tasks/{task_id}")
def delete_task(task_id: int):
for t in tasks:
if t.id == task_id:
tasks.remove(t)
return {"message": "Task deleted"}
raise HTTPException(status_code=404, detail="Task not found")
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="127.0.0.1", port=8000)
This Python code creates a task management API using FastAPI, leveraging Pydantic models for data validation and type enforcement.
It defines a Task model with an id, task, and done status, and initializes a list of tasks.
The API includes endpoints to perform CRUD operations on tasks: the /tasks endpoint allows GET requests to retrieve the task list and POST requests to add a new task, automatically validating incoming data.
The /tasks/{task_id} endpoint allows specific task retrieval with GET, updating with PUT, and deletion with DELETE, returning a 404 error if a task with the specified id is not found.
FastAPI's asynchronous capabilities and integrated documentation make this API efficient and easy to test, ideal for rapid development.
5. Testing APIs
Testing is critical, especially when creating an API that other applications will consume.
Flask and FastAPI provide excellent support for unit testing, making it easy to verify each endpoint’s behavior.
To make testing easier, I’d recommend using pytest for general test structure, as it’s compatible with both Flask and FastAPI.
For FastAPI specifically, TestClient is a helpful tool to mock HTTP requests and check responses.
You will need to install httpx with pip:
pip install httpxHere’s an example for testing a FastAPI endpoint:
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_get_tasks():
response = client.get("/tasks")
assert response.status_code == 200
assert "tasks" in response.json()
With both frameworks, testing is straightforward and allows you to verify that your API behaves as expected, especially as it evolves.
6. Comparison Between Flask and FastAPI
Let's see a comparison between Flask and FastAPI:
If you’re working on a quick prototype or a smaller project, Flask’s simplicity might be all you need.
For projects that require high concurrency, data validation, or auto-documentation, FastAPI provides a more powerful, feature-rich environment.
7. Conclusion
Both Flask and FastAPI have strengths that make them suited to different types of projects.
If you’re new to Python web development, starting with Flask can help you understand the basics before moving to something more advanced.
FastAPI, on the other hand, is an ideal choice if you’re looking for modern, high-performance API development with built-in validation and documentation.
No matter which you choose, Python offers a robust ecosystem for API development.
Both frameworks will allow you to create APIs that can power diverse applications, from simple websites to complex microservices.
The key is to experiment, understand each framework's strengths, and pick the right tool for your needs.
Article originally published at: https://developer-service.blog/how-to-quickly-build-apis-in-python/