Pular para o conteúdo principal

Especificações

A seguir estão descritos os itens técnicos que devem ser atendidos no Gov.pi Conecta, com as boas práticas esperadas em cada especificação.

Padrão de API REST​

As APIs devem ser RESTful, seguindo as melhores práticas de utilização do Protocolo HTTP.

Verbos do Protocolo HTTP​

  • GET → solicita a representação de um recurso, retornando apenas dados.
  • POST → submete uma entidade a um recurso específico, causando mudanças no estado ou efeitos no servidor.
  • PUT → substitui todas as representações atuais do recurso pela carga enviada.
  • PATCH → aplica modificações parciais em um recurso.
  • DELETE → remove um recurso específico.

Fonte: MDN Web Docs – Métodos HTTP

Padronização das rotas​

As rotas devem seguir um padrão único para facilitar o consumo das APIs. Exemplos:

  • Spinal Case: /api/v1/lista-de-produtos
  • Snake Case: /api/v1/lista_de_produtos
  • Camel Case: /api/v1/listaDeProdutos
  • Pluralize: /api/v1/produtos
  • Singularize: /api/v1/produto

Evitar operações nos paths​

Não utilizar verbos ou operações nos endpoints (ex.: /produtos/consultar, /produtos/apagar).
Os métodos HTTP já representam a operação:

  • GET /api/produtos → consultar produtos
  • POST /api/produtos → cadastrar produto
  • DELETE /api/produtos/{id} → remover produto

Paths extensos​

Evitar mais de 2 níveis de aninhamento após a URL base.
Exemplo a evitar: GET /baseUrl/perfis/empresas/{sigla}/matriculas/{matriculaId}/colaboradores/{colaboradorId}/ferias/requisicoes

Códigos de resposta​

Utilizar corretamente os códigos HTTP (2xx, 3xx, 4xx, 5xx).

  • 200 (OK), 201 (Created), 204 (No Content)
  • 400 (Bad Request), 401 (Unauthorized), 404 (Not Found)
  • 500 (Internal Server Error)

Boas práticas necessárias​

Versionamento​

Os endpoints devem conter versão clara, geralmente na URL:
Exemplo: GET https://base-url.example.com/api/v1/produtos

Stateless​

Cada requisição deve ser independente. A API não deve manter estado entre chamadas.

Autenticação​

Usar padrões seguros de autenticação.

  • Recomendado: OAuth2
  • Aceitos: JWT, Basic Auth (desde que documentados corretamente)

Documentação aberta​

Todas as APIs devem ter documentação clara de endpoints, requests e responses.
Exemplo: Swagger/OpenAPI.

Requisitos adicionais​

JSON como padrão​

As APIs devem aceitar e responder em JSON.
Definir o cabeçalho corretamente:
Content-Type: application/json

Página de healthcheck​

Incluir endpoint de verificação simples da aplicação.
Exemplo:
GET /health → retorna status da API.

Cache​

Permitir cache em respostas quando apropriado para melhorar desempenho.

Filtragem, ordenação e paginação​

  • Filtragem: permitir parâmetros para refinar resultados.
  • Ordenação: permitir sort por campos relevantes.
  • Paginação: obrigatório em endpoints que retornam grandes volumes de dados.

Boas práticas de segurança​

  1. Autenticação segura
    Usar OAuth2 ou equivalente.
  2. Comunicações HTTPS
    Toda comunicação deve ser criptografada.

    Fonte: Mandic – Segurança em APIs REST

  3. Não expor informações confidenciais em URLs
    Nunca incluir credenciais, chaves ou tokens em parâmetros de URL.

    Fonte: Akamai – API Security Best Practices