Python: Criar uma API REST

Como criar uma API REST usando Flask

👋 Bem-vindo à documentação do Stackhero!

Stackhero oferece uma solução cloud Python pronta a usar que proporciona uma série de benefícios, incluindo:

  • Implemente a sua aplicação em segundos com um simples git push.
  • Utilize o seu próprio nome de domínio e beneficie da configuração automática de certificados HTTPS para uma segurança reforçada.
  • Desfrute de tranquilidade com backups automáticos, atualizações com um clique, e preços simples, transparentes e previsíveis.
  • Obtenha performance ótima e segurança robusta graças a uma VM privada e dedicada.

Poupe tempo e simplifique a sua vida: só leva 5 minutos para experimentar a solução de hospedagem cloud Python do Stackhero!

Esta documentação é um guia amigável para iniciantes sobre como criar uma API REST em Python.

Neste exemplo, usamos Flask, um micro-framework leve e fácil de usar que permite criar rapidamente aplicações web.

Pré-requisitos

Antes de começar, certifique-se de que o seu computador está equipado com as seguintes ferramentas:

  1. Python
  2. pip
  3. git
  4. asdf

Se o seu ambiente de desenvolvimento ainda não estiver configurado, consulte o guia Development platform para instruções detalhadas. Alternativamente, pode usar a plataforma online Code-Hero. O Code-Hero fornece um IDE e terminal online, com todas as ferramentas essenciais pré-instaladas, permitindo que comece a programar imediatamente sem qualquer instalação.

API REST Python a correr no Code-Hero, acessível diretamente do navegadorAPI REST Python a correr no Code-Hero, acessível diretamente do navegador

Criar um novo projeto

O primeiro passo é criar um novo diretório de projeto. Para este guia, vamos chamá-lo de myRestApi:

mkdir myRestApi
cd myRestApi

Em seguida, defina a versão do Python para a mais recente disponível usando asdf, e inicialize o repositório Git:

asdf install python latest \
  && asdf local python latest

echo "__pycache__/" >> .gitignore

git init
git add -A .
git commit -m "First commit"

Instalar a dependência Flask

Para este exemplo, só precisamos de uma dependência: Flask.

Flask é um framework web leve que permite o desenvolvimento rápido de aplicações web. É projetado para ser simples e fácil de usar, permitindo que os desenvolvedores criem e implantem serviços web rapidamente. O suporte integrado para roteamento, templating e tratamento de pedidos HTTP faz do Flask uma excelente escolha para criar APIs REST.

Instale Flask (e python-dotenv) usando pip:

pip install Flask python-dotenv

Estamos a instalar aqui os módulos Flask e python-dotenv. Em breve verá por que usamos python-dotenv (spoiler: é para gerir variáveis de ambiente).

Após a instalação, congele as versões dos pacotes num ficheiro requirements.txt:

pip freeze > requirements.txt

Congelar as suas dependências garante que o seu servidor de produção ou colegas usem as mesmas versões que você. Apenas alguns segundos de trabalho podem evitar muitas dores de cabeça futuras.

Implementar a API REST usando Flask

Agora, vamos mergulhar no código!

Crie um ficheiro chamado app.py e insira o seguinte código:

import os
from dotenv import load_dotenv
from flask import Flask, jsonify, request

# Carregar variáveis de ambiente do ficheiro .env quando não estamos em produção
if os.environ.get('ENV') != 'production':
    load_dotenv()

# Criar a aplicação Flask
app = Flask(__name__)

# Conjunto de dados de exemplo
tasks = [
    {
        'id': 1,
        'title': 'Comprar mantimentos',
        'description': 'Leite, Queijo, Pizza, Frutas',
        'done': False
    },
    {
        'id': 2,
        'title': 'Aprender Python',
        'description': 'Aprender os fundamentos da programação em Python',
        'done': False
    }
]

# Rota '/api/tasks' (GET) para listar todas as tarefas
@app.route('/api/tasks', methods=['GET'])
def get_tasks():
    return jsonify({'tasks': tasks})

# Rota '/api/tasks/<task_id>' (GET) para obter uma tarefa específica pelo seu ID
@app.route('/api/tasks/<int:task_id>', methods=['GET'])
def get_task(task_id):
    task = [task for task in tasks if task['id'] == task_id]
    if len(task) == 0:
        return jsonify({'error': 'Tarefa não encontrada'}), 404
    return jsonify({'task': task[0]})

# Rota '/api/tasks' (POST) para criar uma nova tarefa
@app.route('/api/tasks', methods=['POST'])
def create_task():
    if not request.json or 'title' not in request.json:
        return jsonify({'error': 'Título é obrigatório'}), 400
    task = {
        'id': tasks[-1]['id'] + 1,
        'title': request.json['title'],
        'description': request.json.get('description', ""),
        'done': False
    }
    tasks.append(task)
    return jsonify({'task': task}), 201

# Iniciar o servidor API
if __name__ == '__main__':
    if os.environ.get('ENV') == 'production':
        app.run()
    else:
        app.run(host='0.0.0.0', port=8080, debug=True)

Para iniciar o servidor, execute:

python app.py

Com a opção host='0.0.0.0', também pode aceder à sua API usando o navegador quando usa Code-Hero. Basta navegar para http://<XXXXXX>.stackhero-network.com:8080/api/tasks, substituindo <XXXXXX> pelo seu domínio Code-Hero.

Testar a sua API REST

Uma vez que o servidor esteja em execução, pode interagir com ele usando cURL. Aqui estão alguns exemplos:

  • Recuperar todas as tarefas:

    curl -s http://localhost:8080/api/tasks
{
  "tasks": [
    {
      "description": "Leite, Queijo, Pizza, Frutas",
      "done": false,
      "id": 1,
      "title": "Comprar mantimentos"
    },
    {
      "description": "Aprender os fundamentos da programação em Python",
      "done": false,
      "id": 2,
      "title": "Aprender Python"
    }
  ]
}

  • Recuperar a tarefa com ID 2:

    curl -s http://localhost:8080/api/tasks/2
{
  "task": {
    "description": "Aprender os fundamentos da programação em Python",
    "done": false,
    "id": 2,
    "title": "Aprender Python"
  }
}

  • Criar uma nova tarefa:

    curl -s -X POST -H "Content-Type: application/json" \
-d '{"title": "Nova tarefa", "description": "Criada com cURL"}' \
http://localhost:8080/api/tasks
{
  "task": {
    "description": "Criada com cURL",
    "done": false,
    "id": 3,
    "title": "Nova tarefa"
  }
}

Dica: Redirecione a saída para jq para embelezar o JSON. Por exemplo, curl -s http://localhost:8080/api/tasks/2 | jq produz um resultado mais legível.

Exemplo de API REST Python usando Flask, a correr no Stackhero Code-Hero, com o servidor (1) e o cliente usando cURL (2)Exemplo de API REST Python usando Flask, a correr no Stackhero Code-Hero, com o servidor (1) e o cliente usando cURL (2)

Gerir variáveis de ambiente

As variáveis de ambiente são vitais para proteger informações sensíveis, como credenciais de base de dados ou chaves de API. Existem dois principais benefícios em usar variáveis de ambiente:

  1. Os seus segredos não são armazenados no seu repositório Git, garantindo que pessoas não autorizadas não possam aceder aos seus dados sensíveis, mesmo que acedam ao seu código-fonte.
  2. Pode usar credenciais diferentes para diferentes ambientes (por exemplo, produção versus desenvolvimento).

Para gerir variáveis de ambiente, usamos o módulo python-dotenv. Primeiro, instale-o se ainda não o fez:

pip install python-dotenv
pip freeze > requirements.txt

Em seguida, crie um ficheiro .env na raiz do seu projeto e adicione as suas variáveis de ambiente de desenvolvimento. Por exemplo:

ENV="development"
DATABASE_PASSWORD="secretPassword"
THIRD_API_PRIVATE_KEY="secretKey"

Finalmente, adicione o ficheiro .env ao seu .gitignore para manter a segurança:

echo ".env" >> .gitignore

Para aceder a estas variáveis de ambiente em Python, basta usar os.environ.get():

import os

print(os.environ.get('ENV'))

O ficheiro .env é usado apenas para o ambiente de desenvolvimento. Para staging ou produção, defina as variáveis de ambiente no painel de controlo Stackhero na configuração do seu serviço Python.

Preparar Python e Flask para implantação em produção

Embora este guia use o servidor de desenvolvimento integrado do Flask, para produção é essencial usar um servidor WSGI pronto para produção, como o Gunicorn. Siga estes passos:

  1. Instale o Gunicorn:

    pip install gunicorn
pip freeze > requirements.txt

  2. Inicie a sua aplicação usando Gunicorn com o argumento app:app (onde o primeiro app é o nome do ficheiro e o segundo app é a instância Flask):

    ENV=production gunicorn app:app \
  --error-logfile - \
  -b 0.0.0.0:8080

  3. Crie um Makefile para simplificar a mudança entre os modos de desenvolvimento e produção:

    .DEFAULT_GOAL := dev

# Por padrão, o Stackhero para Python executa a regra "run". Nós a substituímos para executar a regra 'prod'.
run: prod

prod:
 	ENV=production gunicorn app:app \
 	  --error-logfile - \
 	  -b 0.0.0.0:8080

dev:
 	python app.py

Pode executar o seu servidor em modo de desenvolvimento usando make dev (ou simplesmente make), e em modo de produção usando make prod.

Implantar o seu código Python em produção

A maneira mais simples de implantar o seu projeto Python é usar o serviço de alojamento em cloud Python da Stackhero. As principais funcionalidades incluem:

  • Implantação com um simples git push
  • Domínio personalizável com gestão automática de certificados TLS (HTTPS)
  • Funciona numa VM privada e dedicada para máxima segurança
  • Suporta HTTP/2, TLS 1.3 (HTTPS), WebSockets, compressão GZIP & Brotli, ETag, e acesso a portas TCP/UDP

Configurar o serviço "Stackhero for Python"

Para implantar o seu código no Stackhero, siga estes passos:

  1. Recupere a sua chave pública usando:

    cat ~/.ssh/id_*.pub

  2. No painel de controlo Stackhero, vá ao seu serviço "Stackhero for Python" e clique no botão "Configurar".

  3. Copie a chave pública do primeiro passo e cole-a no campo "SSH public keys" ou "Key".

  4. Valide a configuração clicando no botão "Validar" na parte inferior da página.

Configuração da chave pública "Stackhero for Python"Configuração da chave pública "Stackhero for Python"

Não tem chaves SSH? Crie-as executando:

ssh-keygen -t ed25519

Finalmente, configure o seu repositório para implantar no Stackhero. Na sua pasta de projeto, adicione um remote Git usando o comando fornecido no seu serviço Stackhero (substitua <XXXXXX> pelo domínio do seu serviço):

git remote add stackhero ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

Comando Git remoteComando Git remote

Implantar em produção

Uma vez que tudo esteja configurado, implante o seu código em produção com um único comando:

git push stackhero main

Certifique-se de adicionar e validar as suas alterações antes de enviar o seu código para produção. No Stackhero Code-Hero, pode rapidamente validar as alterações usando a Command Palette (pressione Ctrl+Shift+P no Windows/Linux ou Cmd+Shift+P no macOS e digite Git: Commit).

Após a implantação, visite o URL da sua API em https://<XXXXXX>.stackhero-network.com/api/tasks (substitua <XXXXXX> pelo domínio do seu serviço) para ver a sua API Flask em ação.

Conclusão

Ao seguir este guia, agora entende como criar uma API REST usando Flask. Com este conhecimento, pode desenvolver e expandir as suas aplicações RESTful com confiança, integrando-as com vários serviços front-end e back-end.

Other articles for Python