25. APIs do Diretório - Boas Práticas

• Introdução

• Diferenciação entre APIs Públicas e APIs Protegidas

  • APIs Públicas

  • Cache-Control nas APIs de Dados Públicos do Diretório

    • Requisitos

    • Execução e Limitação de Taxa (rate-limit):

  • APIs Protegidas

    • Autenticação e Acesso

    • Endpoints de Token:

  • Características principais das APIs protegidas:

    • Exemplos de APIs protegidas:

    • Documentação Swagger

• Melhores Práticas para o Uso da API do Diretório

  • Uso das APIs Públicas

  • Uso das APIs Protegidas

  • Recomendações Gerais

  • Principais Considerações

Introdução

As APIs do Diretório no Open Banking Brasil permitem que os participantes recuperem informações armazenadas no Diretório, facilitando o compartilhamento de dados seguro e eficiente em todo o ecossistema. Essas APIs são cruciais para descobrir participantes disponíveis, recursos técnicos como servidores de autorização ou APIs publicadas, e chaves públicas.

Este guia tem como objetivo fornecer detalhes sobre as APIs abertas e restritas do Diretório, focando nas informações fornecidas por esses endpoints. Ele também oferece as melhores práticas a serem seguidas quanto ao consumo e à política de cache.

Diferenciação entre APIs Públicas e APIs Protegidas

O Diretório oferece dois tipos de APIs, cada uma com finalidades distintas:

·       APIs Abertas: Endpoints acessíveis publicamente, que não exigem mTLS, servem para fins gerais de descoberta, permitindo que os participantes reúnam informações não sensíveis, como detalhes dos participantes e chaves públicas.

·       APIs Restritas: Esses endpoints requerem uma conexão mTLS para garantir uma interação segura e são usados ao acessar dados sensíveis ou seguros. O acesso a essas APIs é concedido após a obtenção de um token de acesso, como parte do fluxo de autenticação.

APIs Públicas

As APIs públicas são endpoints que não exigem autenticação, permitindo que qualquer aplicativo interaja com elas sem usar um certificado TLS ou passar pela autenticação OAuth 2.0. Abaixo estão as APIs públicas disponíveis no Diretório:

Nota: Os dados fornecidos pelas APIs públicas mudam muito raramente, normalmente apenas quando são feitas atualizações significativas. Por isso, é recomendável implementar uma estratégia de cache para evitar chamadas desnecessárias a esses endpoints. A duração do cache deve estar alinhada com a diretiva max-age especificada no cabeçalho Cache-Control (veja a seção de cache para referência). A natureza estável desses dados suporta práticas de cache eficientes e reduz solicitações redundantes, melhorando o desempenho.

Cache-Control nas APIs de Dados Públicos do Diretório

Esta seção é aplicável a todos os endpoints data.* e auth.*, notavelmente o endpoint de /participants e o /well-known.

As respostas da API do Diretório incluem um cabeçalho Cache-Control, que especifica diretivas de cache para os clientes.

Exemplo de Cabeçalho:

Isso indica que:

·       A resposta pode ser armazenada em cache por qualquer cache (pois está marcada como pública).

·       O max-age=900 especifica que a resposta pode ser armazenada por 900 segundos (15 minutos) antes que uma nova solicitação deva ser feita.

Requisitos

·       Cache-Control: Os participantes DEVEM respeitar as diretivas de cache-control e implementar cache local com base no valor de max-age.

·       Cache Local ou Proxy: Para cumprir as políticas de limitação de taxa, espera-se que os participantes utilizem mecanismos de cache local ou proxies organizacionais.

Execução e Limitação de Taxa (rate-limit):

·       Participantes que executarem um número de solicitações muito acima do esperado, com base no cabeçalho de política de cache, podem ter suas requisições bloqueadas (rate-limit) pelos serviços do Diretório

APIs Protegidas

As APIs protegidas mTLS só podem ser acessadas por aplicações (Software Statements) registrados no Diretório e que possuam certificados TLS/Transport válidos emitidos por Autoridades Certificadoras (CAs) autorizadas dentro do Diretório.

Para acessar essas APIs protegidas, o participante deve gerar um token de acesso com o escopo directory:software, chamando o endpoint de token usando o tipo de grant_type client_credentials. As instruções para obter um token de acesso podem ser encontradas em Client Credentials Flow: Obtain Access Token - Raidiam Connect Documentation

Autenticação e Acesso

O fluxo de autenticação para as APIs restritas começa com o endpoint /.well-known/openid-configuration, que fornece os metadados necessários, incluindo URLs para obtenção do token de acesso (/token) e autorização (/auth). Após obter o token de acesso, os participantes podem usá-lo para acessar de forma segura as APIs restritas.

Endpoints de Token:

·       Sandbox: https://matls-auth.sandbox.directory.openfinance.ae/token

·       Produção: https://matls-auth.directory.openfinance.ae/token

Após obter o token de acesso, ele pode ser usado para acessar as operações GET de todas as APIs do Diretório que não retornam dados pessoais.

·       A documentação Swagger para a API do TF está disponível aqui: https://api.connect.raidiam.io/source.yaml

·       As URLs do Host da API são:

o   Sandbox: https://matls-api.sandbox.directory.openfinance.ae

o   Produção: https://matls-api.directory.openfinance.ae

Um exemplo de solicitação contra as APIs protegidas do Diretório pode ser encontrado em: Find All Applications - Raidiam Connect Documentation

Características principais das APIs protegidas:

As APIs protegidas podem ser acessadas por meio de uma conexão mTLS (mutual TLS) com as seguintes URLs base:

·       URL Base do Sandbox: https://matls-api.sandbox.directory.openbankingbrasil.org.br/{endpoint}

·       URL Base de Produção: https://matls-api.directory.openbankingbrasil.org.br/{endpoint}

Exemplos de APIs protegidas:

·       /organisations
Fornece informações sobre todas as organizações que participam do ecossistema Open Banking Brasil.

·       /organisations/{organisationId}
Permite acessar informações detalhadas de uma organização específica identificada por {organisationId}.

·       /organisations/{organisationId}/authorisationservers
Fornece informações sobre todos os servidores de autorização vinculados a um determinado {organisationId}.

·       /organisations/{organisationId}/softwarestatements
Lista todas as declarações de software associadas a um {organisationId} específico.

·       /organisations/{organisationId}/softwarestatements/{softwarestatementId}/assertion
Gera uma Declaração de Software (SSA) para um determinado {organisationId} e {softwarestatementId}.

·       /clients
Lista todos os clientes registrados no diretório. A vantagem sobre a API de declarações de software é que ela retorna todas as declarações de software de todas as organizações, sem a necessidade de fazer uma chamada por {organisationId}.

Essas APIs protegidas fornecem informações sensíveis e detalhadas, que são essenciais para o compartilhamento seguro e autorizado de dados dentro do ecossistema.

Documentação Swagger

Uma lista completa de todos os endpoints disponíveis está disponível na documentação Swagger fornecida pela Raidiam, que abrange vários endpoints.

A especificação Swagger pode ser usada para navegar por todas as operações disponíveis dentro do Diretório e determinar quais endpoints são adequados para diferentes casos de uso.

Observação: Implemente estratégias de backoff exponencial para lidar com solicitações falhadas, evitando sobrecarregar o sistema com chamadas repetidas e garantindo a recuperação suave de erros.

Swagger: https://api.connect.raidiam.io/source.yaml

Melhores Práticas para o Uso da API do Diretório

Para garantir o uso eficiente e seguro das APIs do Diretório, siga as seguintes melhores práticas:

Uso das APIs Públicas

Descoberta Inicial de Dados:

·       Utilize o endpoint /participants para obter informações gerais, como dados sobre participantes ativos e seus endpoints. Isso ajuda a evitar o uso desnecessário de APIs restritas.

Cache Eficiente:

·       Como as informações fornecidas pelas APIs abertas são, em sua maioria, estáticas, recomenda-se fazer cache dos dados para reduzir a frequência das chamadas à API. Por exemplo, o endpoint /participants é atualizado a cada 15 minutos, e o .well-known/openid-configuration também é relativamente estático, então armazenar em cache esses endpoints ajuda a equilibrar a carga do sistema.

Uso das APIs Protegidas

Utilizar Apenas Quando Necessário:

·       As APIs restritas exigem mais recursos devido às conexões mTLS. Utilize essas APIs apenas quando interações seguras forem necessárias. Por exemplo, use /authorisationservers apenas se os dados necessários não estiverem disponíveis no endpoint /participants, como quando se busca servidores de autorização inativos, que não são retornados por este último.

Otimização das Conexões:

·       Implemente conexões mTLS persistentes ou utilize pooling de conexões para lidar com solicitações repetidas às APIs restritas, reduzindo o overhead dos handshakes. Use backoff exponencial para tentar novamente solicitações que falharam.

Recomendações Gerais

Priorizar Dados Abertos:

·       Sempre que possível, inicie a descoberta de dados com APIs abertas para reduzir o uso de endpoints restritos.

Armazenamento Seguro de Tokens:

·       Certifique-se de armazenar tokens e outros dados sensíveis de forma segura, respeitando as políticas de expiração para prevenir acessos não autorizados.

Principais Considerações

·       Use APIs públicas primeiro para obter informações gerais e de descoberta, com o /participants sendo a fonte preferida para descobrir servidores de autorização e recursos ativos.

·       Minimize chamadas a APIs mTLS, utilizando-as apenas para interações seguras e sensíveis.

·       Cache eficiente é crucial para reduzir a carga e garantir um uso suave da API, especialmente para dados majoritariamente estáticos, como /participants, .well-known/openid-configuration, e os diferentes tipos de keystores.

Seguindo essas melhores práticas, os participantes podem garantir uma integração segura, eficiente e escalável dentro do ecossistema do Open Finance Brasil.