Como Criar um API REST com Flask no Ubuntu

Introdução

Neste tutorial, você vai aprender a criar uma API REST simples usando Flask, um framework web leve em Python. Vamos abordar os fundamentos de como configurar um aplicativo Flask, definir rotas, lidar com requisições e retornar respostas JSON. Ao final deste tutorial, você terá uma API funcional que poderá ser extendida e integrada 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 conjunto 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 esta guia sobre o primerio do Linux

• 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 Python no Ubuntu, você pode referir-se ao nosso tutorial sobre Como executar um script Python no 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 para obter a instalação do 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 meuambienteprojeto
root@ubuntu:~# source meuambienteprojeto/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-diretorio-do-arquivo-script

Quando dentro do diretório, crie um novo arquivo Python, app.py, e importe 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 código a seguir:

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 às 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. Estes métodos correspondem às quatro operações básicas de armazenamento persistente—muitas vezes referidas como CRUD (Criar, Ler, Atualizar, Excluir).

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

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 requisição GET é feita em /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 requisiçã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 requisiçã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 requisiçã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 requisiçã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 solicitação DELETE para /api/items/<item_id> remove o item com o item_id especificado do repositório de dados. Se o item for deletado com sucesso, o servidor responde com um código de status 204 No Content, indicando que a exclusão foi bem-sucedida e não há mais conteúdo para retornar.

• Executando a Aplicação: O bloco if __name__ == "__main__": garante que a aplicação Flask seja executada quando o script for executado diretamente.

Passo 4 — Executando e Testando a Sua API

Inicie o servidor Flask usando o seguinte comando:

root@ubuntu:~# python3 app.py

Você deveria notar o servidor Flask executando 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á executando em http://127.0.0.1 e escutando 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 console 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 destes 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.

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 uma aplicação básica de API REST usando Flask. Agora, você pode estender essa API com rotas adicionais, integrar 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.