api-route-design
Projetar APIs RESTful em FastAPI
Projetar endpoints de API requer conhecimento de métodos HTTP, padrões de validação e padrões de resposta. Esta habilidade fornece orientação especializada para construir APIs RESTful robustas em FastAPI com validação de requests, paginação e formatos de resposta consistentes.
Die Skill-ZIP herunterladen
In Claude hochladen
Gehe zu Einstellungen → Fähigkeiten → Skills → Skill hochladen
Einschalten und loslegen
Teste es
Verwendung von "api-route-design". Create a GET endpoint for /users/ with pagination
Erwartetes Ergebnis:
- @router.get("/users/", response_model=PaginatedResponse[UserOut])
- async def list_users(
- skip: int = Query(0, ge=0),
- limit: int = Query(100, ge=1, le=1000),
- ) -> PaginatedResponse[UserOut]:
- users, total = await get_users(skip=skip, limit=limit)
- return PaginatedResponse(
- data=users,
- total=total,
- skip=skip,
- limit=limit,
- has_more=(skip + limit) < total,
- )
Verwendung von "api-route-design". Create a POST endpoint with Pydantic validation
Erwartetes Ergebnis:
- class ItemCreate(BaseModel):
- name: str = Field(..., min_length=1, max_length=100)
- price: float = Field(..., gt=0)
- description: str | None = Field(None, max_length=500)
- @router.post("/items/", response_model=ItemOut, status_code=201)
- async def create_item(item_in: ItemCreate) -> ItemOut:
- return await create_item_db(item_in)
Verwendung von "api-route-design". Design error response format
Erwartetes Ergebnis:
- class ErrorResponse(BaseModel):
- error: str
- detail: str | None = None
- code: str | None = None
- # Usage in endpoint:
- raise HTTPException(
- status_code=status.HTTP_404_NOT_FOUND,
- detail="Item not found",
- )
Sicherheitsaudit
SicherAll 84 static findings evaluated as false positives. The skill is a legitimate FastAPI API design reference document containing documentation and a validation script. The scanner incorrectly flagged regex flags (re.MULTILINE, re.DOTALL) as crypto algorithms, markdown code backticks as shell execution, and HTTP status codes as weak crypto. No actual security risks present.
Qualitätsbewertung
Was du bauen kannst
Criando um novo endpoint de API REST
Criar um novo endpoint GET para recuperar recursos paginados com opções de filtragem, códigos de status adequados e modelagem de resposta.
Validando consistência de design de API
Revisar endpoints existentes para garantir que sigam convenções REST, usem códigos de status corretos e incluam schemas de request/resposta adequados.
Aprendendo padrões de roteamento FastAPI
Entender padrões padrão para definir rotas, validar entrada e estruturar respostas em projetos FastAPI.
Probiere diese Prompts
Criar um endpoint GET do FastAPI em /users/{user_id} que retorna detalhes do usuário. Incluir validação de parâmetro de path, tratamento 404 quando o usuário não for encontrado, e um modelo de resposta para os dados do usuário.Projetar um endpoint GET do FastAPI em /items/ que retorna uma lista paginada de itens. Incluir parâmetros de query skip e limit, filtragem por status, opções de ordenação, e um wrapper PaginatedResponse com indicador has_more.
Criar um endpoint POST em /products/ que aceita uma requisição de criação de produto. Usar modelos Pydantic para validação com restrições de campo (ex: price > 0), retornar status 201 em sucesso, e incluir formatação de resposta de erro.
Projetar um roteador CRUD completo para um recurso chamado 'documents' incluindo: lista com paginação, get por ID, criação com validação, atualização com PATCH, e endpoint de delete. Incluir códigos de status adequados (201 para create, 204 para delete) e tratamento de erros.
Bewährte Verfahren
- Usar substantivos plurais para endpoints de coleção (/users e não /user) e kebab-case para paths com múltiplas palavras (/student-fees)
- Retornar 201 para criação via POST, 204 para DELETE bem-sucedido sem corpo de resposta, e 404 para recursos não encontrados
- Sempre usar parâmetros response_model e envolver respostas paginadas com metadados (total, skip, limit, has_more)
Vermeiden
- Usar GET para operações que mudam estado viola a semântica HTTP e expectativas de cache
- Retornar estruturas de resposta diferentes para casos de sucesso e erro confunde consumidores da API
- Pular response_model remove documentação automática do OpenAPI e benefícios de validação