APIs REST Python com Flask, Connexion e SQLAlchemy – Parte 3

• Por que mais de uma tabela em um banco de dados é útil e importante
• Como as tabelas estão relacionadas umas às outras
• Como o SQLAlchemy pode ajudar você a gerenciar relacionamentos
• Como os relacionamentos ajudam você a criar um aplicativo de miniblog

Para quem é este artigo

Dependências Adicionais

1. Handlebars.js é um mecanismo de modelagem para JavaScript, muito parecido com Jinja2 para Flask.
2. Moment.js é um módulo de análise e formatação de data e hora que facilita a exibição de carimbos de data e hora UTC.

Dados de pessoas estendidos para blogs

# Data to initialize database with
PEOPLE = [
    {
        "fname": "Doug",
        "lname": "Farrell",
        "notes": [
            ("Cool, a mini-blogging application!", "2019-01-06 22:17:54"),
            ("This could be useful", "2019-01-08 22:17:54"),
            ("Well, sort of useful", "2019-03-06 22:17:54"),
        ],
    },
    {
        "fname": "Kent",
        "lname": "Brockman",
        "notes": [
            (
                "I'm going to make really profound observations",
                "2019-01-07 22:17:54",
            ),
            (
                "Maybe they'll be more obvious than I thought",
                "2019-02-06 22:17:54",
            ),
        ],
    },
    {
        "fname": "Bunny",
        "lname": "Easter",
        "notes": [
            ("Has anyone seen my Easter eggs?", "2019-01-07 22:47:54"),
            ("I'm really late delivering these!", "2019-04-06 22:17:54"),
        ],
    },
]

Abordagem da Força Bruta

Vantagens

Desvantagens

Abordagem de banco de dados relacional

Vantagens

Desvantagens

Modelos SQLAlchemy

 1class Person(db.Model):
 2    __tablename__ = 'person'
 3    person_id = db.Column(db.Integer, primary_key=True)
 4    lname = db.Column(db.String(32))
 5    fname = db.Column(db.String(32))
 6    timestamp = db.Column(
 7        db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow
 8    )
 9    notes = db.relationship(
10        'Note',
11        backref='person',
12        cascade='all, delete, delete-orphan',
13        single_parent=True,
14        order_by='desc(Note.timestamp)'
15    )

• 
  Linha 9: Assim como os outros atributos da classe, esta linha cria um novo atributo chamado notes e o define igual a uma instância de um objeto chamado db.relationship . Este objeto cria o relacionamento que você está adicionando ao Person class e é criado com todos os parâmetros definidos nas linhas a seguir.
  
• 
  Linha 10: O parâmetro de string 'Note' define a classe SQLAlchemy que o Person aula será relacionada. A Note class ainda não está definida, e é por isso que é uma string aqui. Esta é uma referência direta e ajuda a lidar com problemas que a ordem das definições pode causar quando algo é necessário e não é definido até mais tarde no código. A 'Note' string permite que a Person class para encontrar a Note class em tempo de execução, que está depois de Person e Note foram definidos.
  
• 
  Linha 11: O backref='person' parâmetro é mais complicado. Ele cria o que é conhecido como referência inversa em Note objetos. Cada instância de uma Note objeto conterá um atributo chamado person . A person atributo referencia o objeto pai que uma Note específica instância está associada. Ter uma referência ao objeto pai (person neste caso) no filho pode ser muito útil se seu código iterar sobre notas e tiver que incluir informações sobre o pai. Isso acontece com frequência surpreendente no código de renderização de exibição.
  
• 
  Linha 12: O cascade='all, delete, delete-orphan' O parâmetro determina como tratar as instâncias do objeto de nota quando as alterações são feitas no pai Person instância. Por exemplo, quando uma Person objeto for excluído, SQLAlchemy criará o SQL necessário para excluir o Person do banco de dados. Além disso, este parâmetro diz para ele também excluir todas as Note instâncias associadas a ele. Você pode ler mais sobre essas opções na documentação do SQLAlchemy.
  
• 
  Linha 13: O single_parent=True parâmetro é necessário se delete-orphan faz parte da cascade anterior parâmetro. Isso diz ao SQLAlchemy para não permitir Note órfão instâncias (uma Note sem pai Person object) existir porque cada Note tem um único pai.
  
• 
  Linha 14: O order_by='desc(Note.timestamp)' O parâmetro informa ao SQLAlchemy como classificar a Note instâncias associadas a uma Person . Quando uma Person objeto é recuperado, por padrão as notes lista de atributos conterá Note objetos em uma ordem desconhecida. O SQLAlchemy desc(...) A função classificará as notas em ordem decrescente da mais recente para a mais antiga. Se esta linha fosse order_by='Note.timestamp' , SQLAlchemy usaria o padrão asc(...) função e ordena as notas em ordem crescente, da mais antiga para a mais recente.
  

 1class Note(db.Model):
 2    __tablename__ = 'note'
 3    note_id = db.Column(db.Integer, primary_key=True)
 4    person_id = db.Column(db.Integer, db.ForeignKey('person.person_id'))
 5    content = db.Column(db.String, nullable=False)
 6    timestamp = db.Column(
 7        db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow
 8    )

• 
  Linha 1 cria a Note classe, herdando de db.Model , exatamente como você fez antes ao criar a Person aula.
  
• 
  Linha 2 diz à classe qual tabela de banco de dados usar para armazenar Note objetos.
  
• 
  Linha 3 cria o note_id atributo, definindo-o como um valor inteiro e como a chave primária para a Note objeto.
  
• 
  Linha 4 cria o person_id atributo e o define como a chave estrangeira, relacionando a Note classe para a Person classe usando o person.person_id chave primária. Isso e o Person.notes atributo, são como SQLAlchemy sabe o que fazer ao interagir com Person e Note objetos.
  
• 
  Linha 5 cria o content atributo, que contém o texto real da nota. O nullable=False parâmetro indica que não há problema em criar novas notas sem conteúdo.
  
• 
  Linha 6 cria o timestamp atributo e exatamente como o Person classe, contém a hora de criação ou atualização para qualquer Note específica instância.
  

Inicializar o banco de dados

 1import os
 2from datetime import datetime
 3from config import db
 4from models import Person, Note
 5
 6# Data to initialize database with
 7PEOPLE = [
 8    {
 9        "fname": "Doug",
10        "lname": "Farrell",
11        "notes": [
12            ("Cool, a mini-blogging application!", "2019-01-06 22:17:54"),
13            ("This could be useful", "2019-01-08 22:17:54"),
14            ("Well, sort of useful", "2019-03-06 22:17:54"),
15        ],
16    },
17    {
18        "fname": "Kent",
19        "lname": "Brockman",
20        "notes": [
21            (
22                "I'm going to make really profound observations",
23                "2019-01-07 22:17:54",
24            ),
25            (
26                "Maybe they'll be more obvious than I thought",
27                "2019-02-06 22:17:54",
28            ),
29        ],
30    },
31    {
32        "fname": "Bunny",
33        "lname": "Easter",
34        "notes": [
35            ("Has anyone seen my Easter eggs?", "2019-01-07 22:47:54"),
36            ("I'm really late delivering these!", "2019-04-06 22:17:54"),
37        ],
38    },
39]
40
41# Delete database file if it exists currently
42if os.path.exists("people.db"):
43    os.remove("people.db")
44
45# Create the database
46db.create_all()
47
48# Iterate over the PEOPLE structure and populate the database
49for person in PEOPLE:
50    p = Person(lname=person.get("lname"), fname=person.get("fname"))
51
52    # Add the notes for the person
53    for note in person.get("notes"):
54        content, timestamp = note
55        p.notes.append(
56            Note(
57                content=content,
58                timestamp=datetime.strptime(timestamp, "%Y-%m-%d %H:%M:%S"),
59            )
60        )
61    db.session.add(p)
62
63db.session.commit()

• 
  Linha 4 foi atualizado para importar a Note classe definida anteriormente.
  
• 
  Linhas 7 a 39 contém o PEOPLE atualizado dicionário contendo nossos dados pessoais, juntamente com a lista de notas associadas a cada pessoa. Esses dados serão inseridos no banco de dados.
  
• 
  Linhas 49 a 61 iterar sobre PEOPLE dicionário, obtendo cada person por sua vez e usando-o para criar uma Person objeto.
  
• 
  Linha 53 itera sobre o person.notes lista, obtendo cada note por sua vez.
  
• 
  Linha 54 descompacta o content e timestamp de cada note tupla.
  
• 
  Linha 55 a 60 cria uma Note objeto e anexa-o à coleção de notas da pessoa usando p.notes.append() .
  
• 
  Linha 61 adiciona a Person objeto p para a sessão de banco de dados.
  
• 
  Linha 63 confirma toda a atividade na sessão para o banco de dados. É nesse ponto que todos os dados são gravados na person e note tabelas no people.db arquivo de banco de dados.
  

Person (
    person_id = None
    lname = 'Farrell'
    fname = 'Doug'
    timestamp = None
    notes = [
        Note (
            note_id = None
            person_id = None
            content = 'Cool, a mini-blogging application!'
            timestamp = '2019-01-06 22:17:54'
        ),
        Note (
            note_id = None
            person_id = None
            content = 'This could be useful'
            timestamp = '2019-01-08 22:17:54'
        ),
        Note (
            note_id = None
            person_id = None
            content = 'Well, sort of useful'
            timestamp = '2019-03-06 22:17:54'
        )
    ]
)

Person (
    person_id = 1
    lname = 'Farrell'
    fname = 'Doug'
    timestamp = '2019-02-02 21:27:10.336'
    notes = [
        Note (
            note_id = 1
            person_id = 1
            content = 'Cool, a mini-blogging application!'
            timestamp = '2019-01-06 22:17:54'
        ),
        Note (
            note_id = 2
            person_id = 1
            content = 'This could be useful'
            timestamp = '2019-01-08 22:17:54'
        ),
        Note (
            note_id = 3
            person_id = 1
            content = 'Well, sort of useful'
            timestamp = '2019-03-06 22:17:54'
        )
    ]
)

$ python build_database.py

Atualizar API REST

1. 
   Não há URL definido para obter todas as notes associado a uma pessoa, apenas um URL para obter uma única nota. Isso tornaria a API REST completa de certa forma, mas o aplicativo da Web que você criará mais tarde não precisa dessa funcionalidade. Por isso, ficou de fora.
   
2. 
   Há a inclusão da última URL /api/notes . Este é um método de conveniência criado para a aplicação web. Ele será usado no mini-blog na página inicial para mostrar todas as notas do sistema. There isn’t a way to get this information readily using the REST API pathing style as designed, so this shortcut has been added.
   

Implement the API

Update Response JSON

 1class PersonSchema(ma.ModelSchema):
 2    class Meta:
 3        model = Person
 4        sqla_session = db.session
 5    notes = fields.Nested('PersonNoteSchema', default=[], many=True)
 6
 7class PersonNoteSchema(ma.ModelSchema):
 8    """
 9    This class exists to get around a recursion issue
10    """
11    note_id = fields.Int()
12    person_id = fields.Int()
13    content = fields.Str()
14    timestamp = fields.Str()
15
16class NoteSchema(ma.ModelSchema):
17    class Meta:
18        model = Note
19        sqla_session = db.session
20    person = fields.Nested('NotePersonSchema', default=None)
21
22class NotePersonSchema(ma.ModelSchema):
23    """
24    This class exists to get around a recursion issue
25    """
26    person_id = fields.Int()
27    lname = fields.Str()
28    fname = fields.Str()
29    timestamp = fields.Str()

class PersonSchema(ma.ModelSchema):
    class Meta:
        model = Person
        sqla_session = db.session
    notes = fields.Nested('NoteSchema', default=[], many=True)

People

 1def read_one(person_id):
 2    """
 3    This function responds to a request for /api/people/{person_id}
 4    with one matching person from people
 5
 6    :param person_id:   Id of person to find
 7    :return:            person matching id
 8    """
 9    # Build the initial query
10    person = (
11        Person.query.filter(Person.person_id == person_id)
12        .outerjoin(Note)
13        .one_or_none()
14    )
15
16    # Did we find a person?
17    if person is not None:
18
19        # Serialize the data for the response
20        person_schema = PersonSchema()
21        data = person_schema.dump(person).data
22        return data
23
24    # Otherwise, nope, didn't find that person
25    else:
26        abort(404, f"Person not found for Id: {person_id}")

Notes

 1def read_one(person_id, note_id):
 2    """
 3    This function responds to a request for
 4    /api/people/{person_id}/notes/{note_id}
 5    with one matching note for the associated person
 6
 7    :param person_id:       Id of person the note is related to
 8    :param note_id:         Id of the note
 9    :return:                json string of note contents
10    """
11    # Query the database for the note
12    note = (
13        Note.query.join(Person, Person.person_id == Note.person_id)
14        .filter(Person.person_id == person_id)
15        .filter(Note.note_id == note_id)
16        .one_or_none()
17    )
18
19    # Was a note found?
20    if note is not None:
21        note_schema = NoteSchema()
22        data = note_schema.dump(note).data
23        return data
24
25    # Otherwise, nope, didn't find that note
26    else:
27        abort(404, f"Note not found for Id: {note_id}")

• Line 13 begins a query against the Note SQLAlchemy objects and joins to the related Person SQLAlchemy object comparing person_id from both Person and Note .
• Line 14 filters the result down to the Note objects that has a Person.person_id equal to the passed in person_id parameter.
• Line 15 filters the result further to the Note object that has a Note.note_id equal to the passed in note_id parameter.
• Line 16 returns the Note object if found, or None if nothing matching the parameters is found.

Updated Swagger UI

Mini-Blogging Web Application

1. 
   The home page (localhost:5000/ ) , which shows all of the blog messages (notes) sorted from newest to oldest
   
2. 
   The people page (localhost:5000/people ) , which shows all the people in the system, sorted by last name, and also allows the user to create a new person and update or delete an existing one
   
3. 
   The notes page (localhost:5000/people/{person_id}/notes ) , which shows all the notes associated with a person, sorted from newest to oldest, and also allows the user to create a new note and update or delete an existing one
   

Navigation

1. The Home button will navigate to the home screen.
2. The People button navigates to the /people screen, showing all people in the database.

Home Page

• 
  Double-clicking on a person’s name will take the user to the /people/{person_id} page, with the editor section filled in with the person’s first and last names and the update and reset buttons enabled.
  
• 
  Double-clicking on a person’s note will take the user to the /people/{person_id}/notes/{note_id} page, with the editor section filled in with the note’s contents and the Update and Reset buttons enabled.
  

People Page

• 
  Single-clicking on a person’s name will populate the editor section of the page with the person’s first and last name, disabling the Create button, and enabling the Update and Delete buttons.
  
• 
  Double clicking on a person’s name will navigate to the notes pages for that person.
  

• 
  If the first and last name fields are empty, the Create and Reset buttons are enabled. Entering a new name in the fields and clicking Create will create a new person and update the database and re-render the table below the editor. Clicking Reset will clear the editor fields.
  
• 
  If the first and last name fields have data, the user navigated here by double-clicking the person’s name from the home screen. In this case, the Update , Delete , and Reset buttons are enabled. Changing the first or last name and clicking Update will update the database and re-render the table below the editor. Clicking Delete will remove the person from the database and re-render the table.
  

Notes Page

• 
  Single-clicking on a note will populate the editor section of the page with the notes content, disabling the Create button, and enabling the Update and Delete buttons.
  
• 
  All other functionality of this page is in the editor section.
  

• 
  If the note content field is empty, then the Create and Reset buttons are enabled. Entering a new note in the field and clicking Create will create a new note and update the database and re-render the table below the editor. Clicking Reset will clear the editor fields.
  
• 
  If the note field has data, the user navigated here by double-clicking the person’s note from the home screen. In this case, the Update , Delete , and Reset buttons are enabled. Changing the note and clicking Update will update the database and re-render the table below the editor. Clicking Delete will remove the note from the database and re-render the table.
  

Web Application

• 
  Each page of the application is a fully formed single page web application.
  
• 
  Each page of the application is driven by JavaScript following an MVC (Model/View/Controller) style of responsibility delegation.
  
• 
  The HTML that creates the pages takes advantage of the Jinja2 inheritance functionality.
  
• 
  The hardcoded JavaScript table creation has been replaced by using the Handlebars.js templating engine.
  
• 
  The timestamp formating in all of the tables is provided by Moment.js.
  

• The HTML for the web application
• The CSS for the web application
• The JavaScript for the web application

Conclusão