What Makes an API RESTful
REST (Representational State Transfer) is an architectural style built around resources identified by URIs, manipulated through a fixed set of HTTP verbs (GET, POST, PUT, PATCH, DELETE), and exchanged in a stateless manner where each request carries all the information the server needs. In Flask, a resource like a book or a user maps to a URL such as /api/books/3, and the verb you use against that URL determines the action, rather than encoding the action in the URL path itself (avoiding things like /api/getBook?id=3).
Cricket analogy: A RESTful resource is like a specific player's scorecard entry in a match database: /matches/1023/players/msdhoni always points to the same record, and whether you GET it, PATCH his runs, or DELETE the entry depends on the verb, not on inventing a new URL for each action.
Setting Up Routes and HTTP Methods
Flask's @app.route decorator accepts a methods argument that restricts which HTTP verbs a view function will handle; by default only GET (and HEAD, OPTIONS) are allowed. A common pattern is to combine a collection endpoint (e.g. /api/books handling GET for listing and POST for creation) with an item endpoint that uses a URL converter like <int:book_id> to capture the resource identifier and handles GET, PUT, and DELETE for that single record. Inside the view function, request.method lets you branch behavior when multiple verbs share one route function.
Cricket analogy: Setting methods=['GET', 'POST'] on a route is like a stadium gate that allows both spectators entering (GET, viewing the match) and vendors restocking supplies (POST, adding new items) through the same gate number, while a separate turnstile handles per-seat check-ins with <int:seat_id>.
from flask import Flask, request, jsonify
app = Flask(__name__)
books = {}
next_id = 1
@app.route('/api/books', methods=['GET', 'POST'])
def books_collection():
global next_id
if request.method == 'POST':
data = request.get_json(silent=True) or {}
if 'title' not in data:
return jsonify({'error': 'title is required'}), 400
book = {'id': next_id, 'title': data['title']}
books[next_id] = book
next_id += 1
return jsonify(book), 201
return jsonify(list(books.values())), 200
@app.route('/api/books/<int:book_id>', methods=['GET', 'PUT', 'DELETE'])
def book_detail(book_id):
book = books.get(book_id)
if book is None:
return jsonify({'error': 'Book not found'}), 404
if request.method == 'PUT':
data = request.get_json(silent=True) or {}
book.update(data)
return jsonify(book), 200
if request.method == 'DELETE':
del books[book_id]
return '', 204
return jsonify(book), 200
if __name__ == '__main__':
app.run(debug=True)Handling Request Data and Responses
Incoming data typically arrives as JSON in the request body, parsed with request.get_json(), or as query parameters accessed through request.args (an ImmutableMultiDict). Outgoing responses should use jsonify() (or, since Flask 1.1, return a plain dict and Flask will jsonify it automatically) paired with the correct HTTP status code as the second element of the returned tuple — 200 for success, 201 for creation, 204 for no-content deletions, 400 for bad input, and 404 when a resource doesn't exist.
Cricket analogy: Using request.get_json() to read a POST body is like an umpire consulting the third-umpire replay feed for the actual delivery data, while request.args is like reading the scoreboard's quick query parameters (over number, current score) glanced at in passing.
Since Flask 1.1, returning a plain Python dict from a view is automatically converted to a JSON response, so return book, 200 works the same as return jsonify(book), 200. Many teams still call jsonify() explicitly for clarity and to support non-dict top-level JSON like lists.
Structuring a Complete CRUD Resource
A well-structured CRUD resource validates input before touching state, returns a 404 immediately when a lookup fails so downstream code never operates on None, and picks status codes that match the outcome rather than defaulting everything to 200. Splitting the collection route (list/create) from the item route (read/update/delete) keeps each function focused on one URL pattern, which also makes it straightforward to later swap this hand-rolled dispatching for a class-based view or a library like Flask-RESTful.
Cricket analogy: Validating input before touching state is like a scorer refusing to log a delivery until the umpire's signal confirms it — you don't update the innings total on unconfirmed data, just as a book creation shouldn't mutate the books dict before the title field is validated.
Don't let a KeyError or AttributeError from missing JSON fields crash your view with a 500 error. Always validate request.get_json() output (it can be None if the body is empty or Content-Type isn't application/json) and return a 400 with a clear error message before accessing expected keys.
- REST maps resources to stable URIs and expresses actions through HTTP verbs, not through verb-laden path names.
- Use @app.route(..., methods=[...]) to restrict a view to specific verbs, and branch on request.method when a route handles more than one.
- Split collection endpoints (list/create) from item endpoints (read/update/delete) using URL converters like <int:id>.
- Parse incoming JSON with request.get_json() and read query parameters with request.args.
- Return the correct status code: 200 (OK), 201 (Created), 204 (No Content), 400 (bad input), 404 (not found).
- Since Flask 1.1, returning a plain dict is automatically jsonified, though jsonify() remains common for clarity.
- Always validate input and check resource existence before mutating state to avoid unhandled exceptions and 500 errors.
Practice what you learned
1. In Flask, what does @app.route('/api/books', methods=['GET', 'POST']) allow?
2. Which status code should a successful resource creation (POST) typically return?
3. How do you access JSON data sent in a POST request body in Flask?
4. Since which Flask version can a view return a plain dict and have it automatically converted to a JSON response?
5. What is the appropriate response for a DELETE request that successfully removes a resource with no body to return?
Was this page helpful?
You May Also Like
Flask-RESTful and jsonify
Explore how Flask-RESTful's class-based Resources and Flask's jsonify() work together to structure clean, consistent JSON APIs.
User Authentication in Flask
Understand the core building blocks of authenticating users in Flask: password hashing, login forms, and session-backed identity.
Session Management in Flask
Understand how Flask's signed cookie-based sessions work, their limitations, and how to configure them securely.
Related Reading
Related Study Notes in Web Development
Browse all study notesWebSockets Study Notes
Web Development · 30 topics
Web DevelopmentWebAssembly Study Notes
WebAssembly · 30 topics
Web DevelopmentgRPC Study Notes
Protocol Buffers · 30 topics
Web DevelopmentSpring Boot Study Notes
Java · 30 topics
Web DevelopmentDjango Study Notes
Python · 30 topics
Web DevelopmentNext.js Study Notes
JavaScript · 30 topics