Como Criar uma API REST: Design, Segurança e Publicação

Para criar uma API REST, liste os recursos que a sua aplicação gere (utilizadores, encomendas, reservas), atribua a cada um um URL como /orders e /orders/{id}, e use métodos HTTP para as ações: GET para ler, POST para criar, PATCH para atualizar, DELETE para remover. Devolva JSON com códigos de estado com significado, valide cada dado recebido, exija autenticação e verificações de permissão por registo no servidor, e pagine as listas. Depois documente os pontos de acesso e publique a API atrás de HTTPS.

Este guia cobre as decisões de design, um conjunto de rotas trabalhado, prompts para um construtor de aplicações com IA e os erros que criam falhas de segurança. Se as APIs são novidade para si, comece por o que é uma API.

Quando precisa de uma API REST

• O seu frontend web precisa de guardar e carregar dados de um servidor
• Uma aplicação móvel, um parceiro ou uma ferramenta de automação precisa de aceder aos seus dados
• Outros serviços lhe enviam eventos (webhooks)
• Está a dividir o trabalho entre uma equipa de frontend e uma equipa de backend

REST é o estilo mais comum, mas não é o único. REST vs GraphQL explica quando um único ponto de acesso de consulta flexível se adapta melhor.

Primeiro o design: recursos e rotas

Escreva os substantivos da sua aplicação e o que as pessoas fazem com eles. Para uma aplicação simples de reservas:

Estes correspondem a criar, ler, atualizar e apagar; veja o que é CRUD. Convenções que vale a pena seguir:

• Substantivos no plural, sem verbos nos URLs: /bookings, e não /getBookings.
• Aninhe apenas um nível quando isso esclarece a propriedade: /bookings/{id}/notes.
• Ações que não são CRUD podem ser sub-recursos: POST /bookings/{id}/cancel é mais claro do que um PATCH mágico.
• Nomes consistentes para os campos, como created_at em todo o lado.

Códigos de estado e erros

Use os códigos HTTP padrão para que os clientes saibam o que aconteceu sem terem de interpretar texto:

Devolva os erros numa única estrutura JSON consistente, por exemplo {"error": {"code": "slot_taken", "message": "Esse horário já não está disponível."}}, e nunca inclua stack traces nem erros da base de dados nas respostas.

Opções e compromissos

Passo a passo

1. Liste os recursos e as rotas como acima, incluindo quem pode chamar cada uma.
2. Modele os dados na sua base de dados com os campos e relações de que precisa.
3. Construa primeiro as rotas de leitura, depois as de criação, atualização e remoção.
4. Valide os dados em cada escrita com uma biblioteca de esquemas: campos obrigatórios, tipos, comprimentos, valores permitidos. Rejeite campos desconhecidos.
5. Adicione autenticação e, depois, autorização por registo: aceder a /bookings/42 tem de verificar que a reserva 42 pertence ao utilizador, e não apenas que alguém iniciou sessão.
6. Pagine todas as listas e limite o tamanho da página.
7. Limite os pedidos no login e nas rotas mais pesadas. Veja limitação de pedidos.
8. Configure CORS apenas se browsers de outros domínios tiverem de chamar a API, e indique explicitamente esses origens. Como corrigir erros de CORS explica os erros que vai encontrar.
9. Escreva documentação e testes para cada rota, incluindo os casos de falha.
10. Publique com segredos em variáveis de ambiente, HTTPS, registos e uma verificação de estado.

Prompts para o seu construtor de IA

Estrutura inicial:

Crie uma API REST para reservas com estas rotas: GET /api/health, GET /api/bookings (paginada, máximo 50 por página), POST /api/bookings, GET /api/bookings/:id, PATCH /api/bookings/:id, DELETE /api/bookings/:id. Guarde os dados na nossa base de dados. Valide os corpos dos pedidos com uma biblioteca de esquemas e rejeite campos desconhecidos. Devolva erros em JSON como {"error": {"code", "message"}} com os códigos de estado corretos (400, 401, 403, 404, 409). Guarde os segredos em variáveis de ambiente.

Segurança:

Exija início de sessão em todas as rotas de reservas. Em cada leitura, atualização e remoção, verifique no servidor que a reserva pertence ao utilizador atual; devolva 404 se não pertencer. Nunca aceite IDs de utilizador nem funções do corpo do pedido. Limite POST /api/bookings a 20 por minuto por utilizador. Registe os erros no servidor sem devolver stack traces.

Documentação:

Escreva uma descrição OpenAPI destas rotas e um README curto com exemplos de pedidos e respostas para cada uma.

Testar a sua API

Teste a partir de fora do frontend, porque os atacantes também o farão:

• Cada rota funciona com dados válidos e devolve a estrutura e o código documentados
• Campos em falta ou inválidos devolvem 400 com uma mensagem clara
• Sem token, devolve 401 em todas as rotas protegidas
• O utilizador A ao pedir o registo do utilizador B por ID recebe 404 ou 403
• As listas estão paginadas; um limit enorme é limitado
• Criações duplicadas ou em conflito devolvem 409, e não 500
• Os limites de pedidos devolvem 429
• As respostas de erro não contêm stack traces, SQL nem segredos
• CORS permite apenas os origens que pretende

Erros comuns

• Verificar o login, mas não a propriedade. O buraco de segurança mais comum em APIs: qualquer utilizador com sessão iniciada pode ler qualquer registo mudando o ID.
• Confiar no cliente. Preços, funções e IDs de utilizador no corpo do pedido podem ser editados.
• Devolver linhas completas da base de dados. Hashes de palavras-passe e campos internos ficam expostos. Escolha o que cada resposta inclui.
• Listas sem limite. Um pedido para todos os registos pode tornar lenta a aplicação inteira.
• 200 OK com uma mensagem de erro dentro. Os clientes e a monitorização não conseguem perceber que falhou.
• CORS configurado para permitir tudo numa API que usa cookies.
• Sem verificação de estado nem registos, por isso fica a saber das falhas através dos utilizadores.

Para uma revisão mais ampla antes do lançamento, veja a lista de verificação de segurança para aplicações criadas com IA.

Criar uma API REST no Mythex

Pode pedir ao Mythex uma API como parte da sua aplicação ou como um serviço próprio. A receita da documentação backend com API REST tem um prompt inicial: indique a sua framework e as rotas, peça erros JSON claros, guarde os segredos em variáveis de ambiente e inclua um Dockerfile. Os backends em contentores em Node, Python, C#, Java e outras são publicados através de um Dockerfile, e o Mythex trata da publicação a partir de Publish (backends de API). Um projeto pode ter um website e um servidor de API lado a lado, e pode alternar entre eles na pré-visualização. Guarde as chaves como segredos do projeto e, se a API precisar de uma base de dados, peça-a no chat. Para trabalho agendado em torno da sua API, veja como executar tarefas em segundo plano.

Perguntas