RESTful APIs with Flask

Key Concepts

• REST Principles
• HTTP Methods
• Resource Representation
• Status Codes
• URL Design
• Flask-RESTful
• Authentication and Authorization

1. REST Principles

REST (Representational State Transfer) is an architectural style for designing networked applications. Key principles include:

• Client-Server Architecture
• Statelessness
• Cacheability
• Layered System
• Uniform Interface

2. HTTP Methods

HTTP methods define the type of operation to be performed on a resource. Common methods include:

• GET: Retrieve a resource
• POST: Create a new resource
• PUT: Update an existing resource
• DELETE: Remove a resource

from flask import Flask, request

app = Flask(__name__)

@app.route('/resource', methods=['GET'])
def get_resource():
    return 'Retrieved resource'

@app.route('/resource', methods=['POST'])
def create_resource():
    return 'Created resource'

@app.route('/resource', methods=['PUT'])
def update_resource():
    return 'Updated resource'

@app.route('/resource', methods=['DELETE'])
def delete_resource():
    return 'Deleted resource'
    

3. Resource Representation

Resources are represented in various formats such as JSON, XML, or HTML. JSON is the most common format due to its simplicity and readability.

from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/resource', methods=['GET'])
def get_resource():
    data = {'id': 1, 'name': 'Example Resource'}
    return jsonify(data)
    

4. Status Codes

HTTP status codes indicate the outcome of the request. Common codes include:

• 200 OK: Successful request
• 201 Created: Resource successfully created
• 400 Bad Request: Invalid request
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server-side error

from flask import Flask, jsonify, abort

app = Flask(__name__)

@app.route('/resource', methods=['GET'])
def get_resource():
    data = {'id': 1, 'name': 'Example Resource'}
    return jsonify(data), 200

@app.route('/resource', methods=['POST'])
def create_resource():
    return 'Created resource', 201

@app.route('/resource', methods=['PUT'])
def update_resource():
    return 'Updated resource', 200

@app.route('/resource', methods=['DELETE'])
def delete_resource():
    return 'Deleted resource', 200

@app.route('/resource/', methods=['GET'])
def get_resource_by_id(id):
    if id != 1:
        abort(404)
    data = {'id': id, 'name': 'Example Resource'}
    return jsonify(data), 200
    

5. URL Design

URLs should be designed to reflect the hierarchical structure of the resources. They should be simple, intuitive, and consistent.

from flask import Flask, jsonify

app = Flask(__name__)

@app.route('/users', methods=['GET'])
def get_users():
    users = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
    return jsonify(users)

@app.route('/users/', methods=['GET'])
def get_user(user_id):
    user = {'id': user_id, 'name': 'Alice'}
    return jsonify(user)
    

6. Flask-RESTful

Flask-RESTful is an extension for Flask that simplifies the creation of RESTful APIs. It provides a Resource class and a request parser.

from flask import Flask
from flask_restful import Api, Resource, reqparse

app = Flask(__name__)
api = Api(app)

class HelloWorld(Resource):
    def get(self):
        return {'message': 'Hello, World!'}

api.add_resource(HelloWorld, '/')

if __name__ == '__main__':
    app.run(debug=True)
    

7. Authentication and Authorization

Authentication verifies the identity of the user, while authorization determines what the user is allowed to do. Common methods include token-based authentication and OAuth.

from flask import Flask, request, jsonify
from functools import wraps

app = Flask(__name__)

def token_required(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        token = request.headers.get('X-API-KEY')
        if not token or token != 'secret-token':
            return jsonify({'message': 'Token is missing or invalid'}), 403
        return f(*args, **kwargs)
    return decorated

@app.route('/protected', methods=['GET'])
@token_required
def protected():
    return jsonify({'message': 'This is a protected resource'})

if __name__ == '__main__':
    app.run(debug=True)