Plataforma de Gestão de APIs

InícioPlataformas

Gestão de APIs

Sumário

Acesso

No Manager API você pode criar suas APIs, Apps, Planos etc.

https://unicamp.signin.platform-production.sensedia.com/ Observação:⚡Clique no botão Unicamp no rodapé da página.

Se for seu primeiro acesso, é necessário primeiro fazer login no Manager (use sua conta “@unicamp.br”).

Depois utilize este formulário do Catálogo de Serviços da DETIC para solicitar a associação sua a um time e para concedermos as permissões de acesso ao seu usuário.

  • Já peça para os desenvolvedores do seu time também fazerem esse primeiro login. No formulário você deve indicar os usernames dos mesmos pelos mesmos motivos citados.

O uso desta plataforma está condicionado ao usuário seguir as diretrizes da Instrução Normativa ConTIC IN-01/2019.

Voltar ao topo

API – definições essenciais

  1. Teams: Deve estar associada sempre a um time;
  2. Portal settings: controla a publicação no portal do desenvolvedor, onde os clientes da sua API podem acessar sua documentação SWAGGER e ter uma primeira interação com ela via Try out;
  3. Plans e Apps: A API deve estar sempre associada a uma App (quem é o cliente da API) e um Plano (restrições de uso).
  4. Interface Completeness: Percentual de completude conforme AG – Adaptative Governance;
  5. TRACE API: clique neste botão para visualizar as chamadas e os status da execução, bem como logging (aba Gateway TRACE).

Voltar ao topo

Ambientes

Os ambientes disponíveis para publicação (deploy) de APIs são:

  • api.des.unicamp.br (desenvolvimento)
  • api.hom.unicamp.br (homologação)
  • api.unicamp.br (produção)

Passos para publicação:

Publicação de ambientes

Voltar ao topo

Workflows, Stages e boas práticas

Foram criados os seguintes Workflows / Stages para o desenvolvimento de APIs seguindo boas práticas:

  1. Stage One: workspace para iniciar a criação da sua API, sem premissa de uso de interceptadores e sem um percentual mínimo de completude da sua API.
  2. Sandbox:
    • Interceptador requerido:
      • Log (na Requisição, em qualquer posição da execução e em qualquer fluxo – recurso ou operação).
    • Maturidade da API: 50% (completude do cadastro da API).
  3. Os stages de desenvolvimento, homologação e produção têm duas possibilidades de uso para cada um, a depender da característica de sua API
    • (A) Caso sua API seja para consumo público ☺️, isto é, não trate de dados sensíveis, pessoais e não trabalhe com dados sob sigilo, utilize os stages * Client Id Validation.
      • O interceptador que dá nome a esse workflow permitirá a rastreabilidade do consumo dessa API, via sua App e Plano associados.
      • Sem o uso dessa estratégia não haverá como consultar na auditoria quem foram os consumidores da API.
      • Dessa forma você passará pelos Workflows stages:
        • Desenv Client Id Validation
        • Homolog Client Id Validation
        • Prod Client Id Validation
    • (B) Caso sua API trabalhe com dados sob sigilo, sensíveis ou pessoais 😨, então você deve usar os stages * OAuth para exigir dos consumidores elegíveis da sua API o clientID e o secret necessários para liberar o uso.
      • Dessa forma você passará pelos Workflows stages:
        • Desenv OAuth
        • Homolog OAuth
        • Prod OAuth
      • Estes stages impõem o uso dos interceptadores Bearer Token RFC6750 v2 e OAuth na sua API.

Abaixo seguem os detalhes desses stages.

  • stage Desenv ou Homolog Client Id Validation
    • Interceptadores requeridos:
      • Client Id Validation (na Requisição, em qualquer posição e fluxo).
      • Log (na Requisição, em qualquer posição e fluxo).
      • Maturidade da API: 60% (completude do cadastro da API).
  • stage Desenv ou Homolog OAuth
    • Interceptadores requeridos:
      • Bearer Token RFC6750 v2 e OAuth (na Requisição, em qualquer posição e fluxo).
      • Log (na Requisição, em qualquer posição e fluxo).
    • Maturidade da API: 60%
  • stage Prod Client Id Validation
    • Equivalente ao de homologação de mesmo nome.
    • Não pode usar Interceptador de Mock.
    • Maturidade da API: 65%
  • stage Prod OAuth
    • Equivalente ao de homologação de mesmo nome.
    • Não pode usar Interceptador de Mock.
    • Maturidade da API: 65%
Pode ou não pode de interceptores

Mensagem de erro no caso de não usar um interceptor requerido:

Interceptor requerido

🔦 Em alguns casos é importante usar o plugin do Desenvolvedor do seu navegador F12 para obter mais detalhes da mensagem de erro que a plataforma exibe.
Correção:

Correção dos interceptors

Observações:

  • Ao mudar o stage da sua API para Desenv (Client ID Validation ou OAuth), esta já deve estar no stage Sandbox;
  • Ao mudar o stage da sua API para Homolog (Client ID Validation ou OAuth), esta já deve estar tanto no stage Desenv correspondente, bem como publicada no ambiente Desenvolvimento Unicamp;
  • Ao mudar o stage da sua API para Prod (Client ID Validation ou OAuth), esta já deve estar no stage Homolog correspondente, bem como publicada no ambiente Homologação Unicamp.

Exemplo: O pré-requisito para passar para o stage Homolog * é a API estar antes implantada no Desenvolvimento Unicamp.

Pré-requisito de deploy

Voltar ao topo

Restringir o acesso das APIs ao seus endpoints (backend) somente para os IPs da plataforma

  1. O endereço api.unicamp.br é um alias no DNS da UNICAMP para a Plataforma de Gestão de API;
    • É também um ambiente cadastrado na plataforma, com certificado TLS/SSL associado, com variáveis de ambiente e APIs também associadas a ele.
  2. A plataforma para esta API faz chamada ao target / endpoint a partir dos IPs de saída (OutboundAdress) da própria plataforma. E estes IPs (management/info) precisam constar na white list do serviço Ingress do Kubernetes e demais pontos, conforme exposto anteriormente.
    • No caso de uso de conectores da plataforma, a fim de poder testar a conectividade deste, é necessário liberar 2 IPs específicos.
    • Favor solicitar a plataforma-api-l@unicamp.br a relação de IPs.

Voltar ao topo

Documentação dos interceptadores de segurança

As demais necessidades da sua API devem ser tratadas no escopo dela usando a paleta de interceptadores disponíveis, principalmente os relacionados a segurança de APIs.

Voltar ao topo

Conectores

O API Manager provê o recurso conectores para integração com Banco de dados, Cloud Provider etc.

A ideia é por exemplo converter protocolo JDBC em chamadas REST com retorno dos dados encapsulados em JSON.

É um recurso interessante no caso de a demanda de negócio não demandar a construção de um serviço (micro-serviço ou backend) para prover dados.

Contudo, o uso desse recurso deve ser feito com bastante critério 📏 observando os aspectos mencionados na próxima seção. ‼️

Considerações de segurança e resiliência para prover APIs que usam conectores

  1. Na API que será cliente do conector criado:
    • ⚡ Usar obrigatoriamente interceptadores como:
      • SQL Threat Protection para sanitizar a entrada de dados;
      • XSS Threat Protection, bem como demais interceptadores para barrar ataques;
      • Nestes interceptadores é possível indicar expressões a serem ignoradas. Por exemplo: algumas cidades chamam “ALTER”, então para uma consulta de cidades, neste caso poderia ser colocado para ignorar essa expressão.
      • Usar os interceptadores Bearer Token e OAuth para restringir quem pode usar sua API e restringir assim o acesso aos dados.
    • ⚡ Avaliar de usar o interceptador de cache, caso a volatilidade dos dados seja baixa.
  2. ⚡ No Plano da API que consome esse conector, usar interceptador RATE LIMIT para barrar acessos massivos de um mesmo IP num curto espaço de tempo por exemplo. E o recurso de payload size para evitar sobrecarga no processamento de requisições.
  3. ⚡ Se valer de outras precauções, como não criar conector para a base transacional do seu sistema, caso as consultas possam ser para dados D-1 (dia anterior).
  4. ⚡ Ao invés das queries executarem direto nas tabelas, utilize views que expõem só as colunas e registros necessários para o escopo da API.
  5. ⚡ Se a API for apenas para consulta de dados, no conector indicar um usuário de banco que tenha permissão somente de leitura na base de dados. Ideal ser um usuário de banco exclusivo para APIs do mesmo contexto.
  6. ⚡ Permitir que somente os IPs de Outbound do Gateway da Sensedia (consulte a URL management/info) possam acessar o recurso de conector (Java ou contêiner).
  7. ⚡ Adicionar o IP do Conector (Java ou contêiner) na ACL do banco de dados que proverá os dados.
  8. ⚡ Utilize a implantação do tipo contêiner / docker para ter alta disponibilidade do conector, ao invés da opção Java/Jar. Dessa forma, será possível configurar um cluster de conectores (kubernetes auto-scaling) ao invés de um único conector e evitar um SPF (Single Point of Failure).

Consulte aqui a documentação deste recurso.

Nesta documentação, Sensedia – API Patterns v2.2 – Guia prático, as páginas 17 e 18 tratam de um tema importante relacionado a paginação dos dados retornados pelo conector.

Voltar ao topo