O Que É uma REST API? APIs Web Orientadas a Recursos
Uma REST API é uma interface web que expõe recursos em URLs e os manipula com métodos HTTP padrão, retornando dados estruturados como JSON.
REST, abreviação de Representational State Transfer, é o estilo dominante para APIs web. Recursos como usuários, builds ou deployments têm cada um uma URL, e você age sobre eles com GET, POST, PUT e DELETE. A maioria das ferramentas de CI automatiza uma plataforma chamando sua REST API, então entender REST ajuda a ler e depurar integrações de pipeline.
Recursos e URLs
Em REST, toda entidade é um recurso identificado por uma URL, como /deployments/42. Você opera sobre ela com métodos HTTP em vez de chamar funções nomeadas, o que mantém a interface previsível.
Métodos mapeiam para ações
- GET lê um recurso.
- POST cria um novo.
- PUT ou PATCH atualiza um existente.
- DELETE o remove.
Status codes carregam significado
REST se apoia nos status codes HTTP para relatar resultados: 200 para sucesso, 201 para criado, 400 para uma requisição inválida, 401 ou 403 para problemas de autenticação, 404 para não encontrado, e 5xx para erros de servidor. Um pipeline lê esses códigos para decidir se prossegue ou falha.
Autenticação
REST APIs geralmente exigem um token, muitas vezes um bearer token ou uma credencial OAuth, enviado em um header Authorization. O CI armazena esse token como um segredo e o anexa a cada chamada.
REST APIs em CI/CD
Disparar um deploy, criar um release, postar um status check ou consultar o resultado de um build são todas chamadas REST em muitos pipelines. Uma resposta não-2xx é o sinal de que o step deve falhar ou repetir.
Lidando com chamadas de API instáveis
Um 5xx ou uma conexão derrubada em um GET idempotente geralmente é seguro de repetir; um 4xx significa que sua requisição está errada e repetir não vai ajudar. Os runners da Latchkey repetem automaticamente falhas de rede transitórias para endpoints de API comuns, para que soluços breves de upstream não quebrem um step de deploy.
Principais conclusões
- REST expõe recursos em URLs e age sobre eles com métodos HTTP padrão.
- Os status codes relatam resultados, então respostas não-2xx guiam as decisões do pipeline.
- Repita chamadas idempotentes em caso de 5xx ou erros de rede, mas nunca em um 4xx.