Versionamento e documentação de APIs

Colocando IA em Produção com FastAPI

Matt Eckerle

Software and Data Engineering Leader

Por que versionar APIs?

Endpoints da API como itens do menu
Manter clientes antigos satisfeitos
Alguns clientes querem novas opções
Iterar sem impactar clientes existentes

Um restaurante

API para jobs de IA na nuvem

from pydantic import BaseModel

class AIJobV1(BaseModel):
    job_name: str
    data: bytes

class AIJobV1(BaseModel):
    job_name: str
    data: bytes
    config: dict

Logo do FastAPI AI Cloud

Endpoints versionados

from pydantic import BaseModel

class AIJobV1(BaseModel):
    job_name: str
    data: bytes


class AIJobV2(BaseModel):
    job_name: str
    data: bytes
    config: dict

from fastapi import FastAPI

app = FastAPI()

@app.post("/v1/ai-job")
def ai_job_v1(job: AIJobV1):
    ...


@app.post("/v2/ai-job")
def ai_job_v2(job: AIJobV2):
    ...

Motivos para atualizar a versão do endpoint

Mudança incompatível no schema
Mudança na função subjacente
- Código do modelo atualizado
- Conjunto de treino do modelo atualizado
- Pré/pós-processamento atualizado

Iteração com campos opcionais

Nem sempre é preciso versionar para iterar
Campos opcionais permitem dados extras sem quebrar schemas

from pydantic import BaseModel

class AIJobV1(BaseModel):
    job_name: str
    data: bytes


from typing import Optional

class AIJobV1(BaseModel):
    job_name: str
    data: bytes
    config: Optional[dict]

Documentando APIs com Swagger

Ferramenta padrão para documentar APIs
- Acompanha endpoints e versões
- Baseada nos metadados do padrão OpenAPI

Logo do OpenAPI

Swagger UI

URL do Swagger Swagger UI

Swagger UI de um endpoint

FastAPI Swagger UI para endpoint

Usando o campo de descrição do FastAPI

from fastapi import FastAPI

app = FastAPI(
    description="AI Job API"
)

FastAPI Swagger UI com cabeçalho de descrição

Vamos praticar!

Colocando IA em Produção com FastAPI