Como criar um API REST com Flask no Ubuntu

Introdução

Neste tutorial, você vai aprender a criar um simples API REST usando Flask, um framework web leve em Python. Vamos abranger os fundamentos de como configurar uma aplicação Flask, definir rotas, lidar com requisições e retornar respostas em JSON. Ao final deste tutorial, você terá um API funcional que pode ser extendido e integrado com outras aplicações.

Pré-requisitos

• Um servidor executando Ubuntu e um usuário não-root com privilégios de sudo e uma firewall ativa. Para orientações sobre como configurar isso, por favor escolha sua distribuição do este lista e siga com nossa guia de configuração inicial do servidor. Certifique-se de trabalhar com uma versão suportada do Ubuntu.

• Familiaridade com a linha de comando do Linux. Para uma introdução ou atualização sobre a linha de comando, você pode visitar essa guia sobre primeiro Linux command line

• Um entendimento básico de programação em Python.

• O Python 3.7 ou superior instalado no seu sistema Ubuntu. Para aprender a executar um script de Python no Ubuntu, você pode referir-se a nossa tutorial sobre Como executar um script de Python em Ubuntu.

Passo 1 — Configurando o seu Ambiente Flask

O Ubuntu 24.04 vem com Python 3 por padrão. Abra o terminal e execute o comando a seguir para verificar duas vezes a instalação de Python 3:

root@ubuntu:~# python3 --version
Python 3.12.3

Se o Python 3 já estiver instalado no seu computador, o comando acima retornará a versão atual da instalação de Python 3. Caso contrário, você pode executar o seguinte comando e obter a instalação de Python 3:

root@ubuntu:~# sudo apt install python3

A seguir, você precisará instalar o gerenciador de pacotes pip no seu sistema:

root@ubuntu:~# sudo apt install python3-pip

Uma vez que o pip estiver instalado, vamos instalar o Flask.

Você vai instalar o Flask via pip. É recomendado fazer isso em um ambiente virtual para evitar conflitos com outros pacotes no seu sistema.

root@ubuntu:~# python3 -m venv meuambientevirtual
root@ubuntu:~# source meuambientevirtual/bin/activate

root@ubuntu:~# pip install Flask

Passo 2 – Criar um Aplicativo Flask

A próxima etapa é escrever o código Python para o aplicativo Flask. Para criar um novo arquivo, navegue até o diretório de sua escolha:

root@ubuntu:~# cd ~/caminho-para-o-diretorio-do-arquivo-script

Quando dentro do diretório, crie um novo arquivo Python, app.py, e importe o Flask. Em seguida, inicialize um aplicativo Flask e crie uma rota básica.

root@ubuntu:~# nano app.py

Isso abrirá um editor de texto em branco. Escreva sua lógica aqui ou copie o seguinte código:

from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/')
def hello_world():
    return jsonify(message="Hello, World!")

# Armazenamento de dados em memória
items = [{"id": 1, "name": "This is item 1"}, {"id": 2, "name": "This is item 2"}]

Passo 3 – Criando Rotas RESTful

Nesta seção, definiremos rotas em nosso aplicativo Flask que correspondem a diferentes ações que um usuário pode realizar na API. Cada rota manterá um método HTTP específico.

GET, POST, PUT, e DELETE. Esses métodos correspondem às quatro operações básicas de armazenamento persistente— frequentemente referidas como CRUD (Criar, Ler, Atualizar, Excluir).

Adicione as seguintes rotas ao seu arquivo de script app.py em Python:

from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/')
def hello_world():
    return jsonify(message="Hello, World!")

# Armazenamento em memória
items = [{"id": 1, "name": "This is item 1"}, {"id": 2, "name": "This is item 2"}]

# Requisição GET: Recuperar todos os itens
@app.route('/api/items', methods=['GET'])
def get_items():
    return jsonify(items)

# Requisição GET: Recuperar um item específico por ID
@app.route('/api/items/<int:item_id>', methods=['GET'])
def get_item(item_id):
    item = next((item for item in items if item["id"] == item_id), None)
    if item is None:
        return jsonify({"error": "Item not found"}), 404
    return jsonify(item)

# Requisição POST: Criar um novo item
@app.route('/api/items', methods=['POST'])
def create_item():
    new_item = {"id": len(items) + 1, "name": request.json.get('name')}
    items.append(new_item)
    return jsonify(new_item), 201

# Requisição PUT: Atualizar um item existente
@app.route('/api/items/<int:item_id>', methods=['PUT'])
def update_item(item_id):
    item = next((item for item in items if item["id"] == item_id), None)
    if item is None:
        return jsonify({"error": "Item not found"}), 404
    item['name'] = request.json.get('name', item['name'])
    return jsonify(item)

# Requisição DELETE: Excluir um item
@app.route('/api/items/<int:item_id>', methods=['DELETE'])
def delete_item(item_id):
    global items
    items = [item for item in items if item["id"] != item_id]
    return '', 204

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

Vamos saber mais sobre o que cada função faz:

• Importações do Flask: O código importa componentes necessários do Flask: Flask, jsonify, e request.

• Armazenamento em Memória: items é uma simples lista de dicionários que atua como um armazenamento temporário para a API. Cada item tem um id e um name.

• GET /api/items: Quando uma solicitação GET é feita para /api/items, o servidor retorna uma lista de todos os itens no repositório de dados de itens. Isso é útil para recuperar todos os recursos em uma coleção.

• POST /api/items: Uma solicitação POST para /api/items permite que o cliente crie um novo item. O servidor espera um objeto JSON contendo os detalhes do novo item no corpo da solicitação. Após criar o item, o servidor responde com o item recém-criado e um código de status 201 Created.

• PUT /api/items/<int:item_id>: Uma solicitação PUT para /api/items/<item_id> é usada para atualizar um item existente com o item_id especificado. O cliente envia os dados atualizados no corpo da solicitação, e o servidor modifica o item existente. Se o item não for encontrado, o servidor retorna um erro 404 Not Found.

• DELETE /api/items/<int:item_id>: Uma requisição DELETE para /api/items/<item_id> remove o item com o item_id especificado do repositório de dados. Se o item for excluído com sucesso, o servidor responde com um código de status 204 No Content, indicando que a exclusão foi bem-sucedida e que não há mais conteúdo a ser retornado.

• Executando o Aplicativo: O bloco if __name__ == "__main__": garante que o aplicativo Flask seja executado quando o script é executado diretamente.

Passo 4 — Executando e Testando sua API

Inicie o servidor Flask usando o comando a seguir:

root@ubuntu:~# python3 app.py

Você deveria notar o servidor Flask rodando com a saída abaixo:

Output
* Serving Flask app 'app'
 * Debug mode: on
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on http://127.0.0.1:5000
Press CTRL+C to quit
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 837-877-972

A partir da saída acima, você pode notar que o servidor está rodando em http://127.0.0.1 e está ouvindo na porta 5000.

Agora, você pode testar os endpoints usando curl, Postman, ou outro cliente HTTP. Neste tutorial, você usará curl para testar os endpoints e enviar pedidos HTTP.

Abra outra consola Ubuntu e execute os comandos curl abaixo um a um:

• GET: curl http://127.0.0.1:5000/api/items
• POST: curl -X POST -H "Content-Type: application/json" -d '{"name": "This is item 3"}' http://127.0.0.1:5000/api/items
• PUT: curl -X PUT -H "Content-Type: application/json" -d '{"name": "This is updated item 1"}' http://127.0.0.1:5000/api/items/1
• DELETE: curl -X DELETE http://127.0.0.1:5000/api/items/1

Vamos ver cada um desses comandos em ação:

root@ubuntu:~# curl http://127.0.0.1:5000/api/items

Output
[
  {
    "id": 1,
    "name": "This is item 1"
  },
  {
    "id": 2,
    "name": "This is item 2"
  }
]

Você notará que o servidor retorna uma lista de todos os itens no armazenamento de itens.

Usando o método POST, vamos adicionar um novo item ao armazenamento de dados.

root@ubuntu:~# curl -X POST -H "Content-Type: application/json" -d '{"name": "This is item 3"}' http://127.0.0.1:5000/api/items

Output
{
  "id": 3,
  "name": "This is item 3"
}

* Running on http://127.0.0.1:5000
Press CTRL+C to quit
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 837-877-972
127.0.0.1 - - [23/Aug/2024 06:57:27] "GET /api/items HTTP/1.1" 200 -
127.0.0.1 - - [23/Aug/2024 06:59:56] "POST /api/items HTTP/1.1" 201 -

Agora, vamos executar uma solicitação PUT. Uma solicitação PUT para /api/items/<item_id> atualizará um item existente com o item_id especificado.

root@ubuntu:~# curl -X PUT -H "Content-Type: application/json" -d '{"name": "This is updated item 1"}' http://127.0.0.1:5000/api/items/1

Output
{
  "id": 1,
  "name": "This is updated item 1"
}

Agora, vamos executar uma solicitação GET para ver o item 1 atualizado.

root@ubuntu:~# curl http://127.0.0.1:5000/api/items/1

Output
{
  "id": 1,
  "name": "This is updated item 1"
}

Por fim, vamos executar uma solicitação DELETE para excluir um item do armazenamento.

root@ubuntu:~# curl -X DELETE http://127.0.0.1:5000/api/items/1

Isso excluirá o item 1 do armazenamento.

Para verificar isso, vamos executar uma solicitação GET.

root@ubuntu:~# curl http://127.0.0.1:5000/api/items

Output
[
  {
    "id": 2,
    "name": "This is item 2"
  },
  {
    "id": 3,
    "name": "This is item 3"
  }
]

Você notará que o item 1 já não está presente e foi excluído permanentemente.

Conclusão

Neste tutorial, você construiu um aplicativo básico de API REST usando Flask. Agora, você pode extendê-la com rotas adicionais, integrá-la com um banco de dados ou deployá-la para uma plataforma de nuvem como o DigitalOcean. Flask é uma ferramenta poderosa para construir APIs rapidamente e eficientemente, e com estes fundamentos, você está pronto para começar a construir aplicações mais complexas.