Construindo APIs RESTful Com Flask: Abordagem Faça-Você-Mesmo

() translation by (you can also view the original English article)

Representational State Transfer (REST) é um estilo de projeto de arquitetura de desenvolvimento web que se refere à separação lógica dos recursos da API, habilitando fácil acesso, manipulação e dimensionamento. Componentes reusáveis são escritos para sere facilmente adminitrados através de requisições HTTP simples e intuitivas, como GET, POST, PUT, PATCH e DELETE (pode ter mais, mas essas são as mais usadas).

Apesa da aparência, REST não exige um protocolo ou padrão. Apenas prepara um estilo arquitetural de software para a escrita de aplicações web e APIs, resultando na simplificação de interfaces dentro e fora da aplicação. APIs de serviços web escritas seguindo os princípios REST são chamadas de APIs RESTful.

Nessa série de três partes, cobriremos maneiras diferentes que APIs RESTful podem ser criadas usando Flask, uma framework web. Nessa primeira parte, cobriremos como criar APIs REST baseadas em classes, na mão, ou seja, implementando sem uso de extensões de terceiros. Nas outras partes da série, cobriremos como lançar mão de várias extensões do Flask para construir APIs REST mais efetivas e de forma mais fácil.

Assumimos que tenha entendimento básico do Flask e boas práticas de configuração de ambientes usando virtualenv, que devem ser seguidas ao desenvolver aplicações em Python.

Instalando Dependências

Os pacotes a seguir precisam ser instalados para a aplicação que desenvolveremos.

1	$ pip install flask
2	$ pip install flask-sqlalchemy

Os comando acima deveriam instalar todos os pacotes requeridos para a aplicação funcionar.

A Aplicação Flask

Para esse tutorial, criaremos uma pequena aplicação onde teremos um modelo Product trivial. E demonstraremos como escrever uma API Restful para o mesmo. Abaixo temos a estrutura da aplicação.

flask_app/
    my_app/
        - __init__.py
        product/
            - __init__.py      // Empty file
            - models.py
            - views.py
    - run.py

Não criaremos front-end para essa aplicação já que os pontos de acesso das APIs RESTful podem ser testadas diretamente com chamadas HTTP usando vários outros métodos.

flask_app/my_app/init.py

from flask import Flask
from flask.ext.sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:////tmp/test.db'
db = SQLAlchemy(app)

from my_app.catalog.views import catalog
app.register_blueprint(catalog)

db.create_all()

No arquivo acima, a aplicação foi configurada com a inicialização das extensões e a criação da base de dados. A última declaração cria uma nova base de dados no local provido por SQLALCHEMY_DATABASE_URI se uma base de dados ainda não existir no local, caso contrário, carrega a aplicação com a base existente.

flask_app/my_app/catalog/models.py

from my_app import db

class Product(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(255))
    price = db.Column(db.Float(asdecimal=True))

    def __init__(self, name, price):
        self.name = name
        self.price = price

    def __repr__(self):
        return '<Product %d>' % self.id

No arquivo acima, criamos um modelo bem trivial para salvar o nome e preço de um Product (produto). Isso criará uma tabela no SQLite correspondendo ao detalhes providos no modelo.

flask_app/my_app/catalog/views.py

import json
from flask import request, jsonify, Blueprint, abort
from flask.views import MethodView
from my_app import db, app
from my_app.catalog.models import Product

catalog = Blueprint('catalog', __name__)

@catalog.route('/')
@catalog.route('/home')
def home():
    return "Welcome to the Catalog Home."


class ProductView(MethodView):

    def get(self, id=None, page=1):
        if not id:
            products = Product.query.paginate(page, 10).items
            res = {}
            for product in products:
                res[product.id] = {
                    'name': product.name,
                    'price': str(product.price),
                }
        else:
            product = Product.query.filter_by(id=id).first()
            if not product:
                abort(404)
            res = {
                'name': product.name,
                'price': str(product.price),
            }
        return jsonify(res)

    def post(self):
        name = request.form.get('name')
        price = request.form.get('price')
        product = Product(name, price)
        db.session.add(product)
        db.session.commit()
        return jsonify({product.id: {
            'name': product.name,
            'price': str(product.price),
        }})

    def put(self, id):
        # Update the record for the provided id
        # with the details provided.
        return

    def delete(self, id):
        # Delete the record for the provided id.
        return


product_view =  ProductView.as_view('product_view')
app.add_url_rule(
    '/product/', view_func=product_view, methods=['GET', 'POST']
)
app.add_url_rule(
    '/product/<int:id>', view_func=product_view, methods=['GET']
)

O grande problema desse tutorial é lidar com o arquivo acima. Flask provê um utilitário chamado visões conectáveis que nos permitem criar visões na forma de classes ao invés de funções. Despache baseado em métodos (MethodView) é uma implementação de visão conectável que permite escrever métodos correspondentes aos métodos HTTP. No exemplo acima, escrevemos métodos get() e post() correspondendo aos métodos HTTP GET e POST.

Rotas também são implementadas diferentemente, ao final do arquivo acima. Podemos especificar métodos que suportaremos para qualquer regra em particular. Qualquer outra chamada HTTP encontrará Error 405 Method not allowed.

Executando a Aplicação

Para executar a aplicação, execute o script run.py. O conteúdo do script é:

1	from my_app import app
2	app.run(debug=True)

Agora execute-o na linha de comando:

1	$ python run.py

Para verificar se a aplicação funciona, digite http://127.0.0.1:5000/ no navegador e uma tela simples de bem vindo deveria aparecer.

Testando a API RESTful

Para testar a API, realizaremos chamadas HTTP usando quaisquer métodos disponíveis. As GET podem ser feitas diretamente pelo navegador. As POST podem ser feitas com uma extensão para Chrome, Postman, ou pela linha de comando com curl, ou podemos usar a biblioteca requests do Python. Usaremos a biblioteca requests para efeitos de demonstração.

Façamos as GET primeiro para garantir que ainda não temos produtos criados. Pelo padrão de APIs RESTful, uma chamada parecida com /product/ deveria listar todos os produtos. Depois, criaremos alguns produtos via POST em /product/ com alguns dados. Então um GET para /product/ deveria listar todos os produtos criados. Para obter um produto em específico, um GET para /product/<id do produto> deveria funcionar. Abaixo, temos um exemplo das chamadas que podem ser feitas usando o exemplo.

1	$ pip install requests
2	$ python
3	>>> import requests
4	>>> r = requests.get('http://localhost:5000/product/')
5	>>> r.json()
6	{}
7	>>> r = requests.post('http://localhost:5000/product/', data={'name': 'iPhone 6s', 'price': 699})
8	>>> r.json()
9	{u'1': {u'price': u'699.0000000000', u'name': u'iPhone 6s'}}
10	>>> r = requests.post('http://localhost:5000/product/', data={'name': 'iPad Pro', 'price': 999})
11	>>> r.json()
12	{u'2': {u'price': u'999.0000000000', u'name': u'iPad Pro'}}
13	>>> r = requests.get('http://localhost:5000/product/')
14	>>> r.json()
15	{u'1': {u'price': u'699.0000000000', u'name': u'iPhone 6s'}, u'2': {u'price': u'999.0000000000', u'name': u'iPad Pro'}}
16	>>> r = requests.get('http://localhost:5000/product/1')
17	>>> r.json()
18	{u'price': u'699.0000000000', u'name': u'iPhone 6s'}

Conclusão

Nesse tutorial, vimos como criar interfaces RESTful para nós mesmo usando o utilitário de visões conectáveis do Flask. Essa é a abordagem mais flexível ao criar APIs REST mas requer muito código a ser escrito.

Existem extensões que tornam a vida mais simples e automatizam bastante a implementação de APIs RESTful. Cobriremos elas nas próxima partes dessa série.