Prodap API Gateway

Essa biblioteca foi criada com o objetivo de padronizar e simplificar a criação de API Gateway nos produtos da Prodap. A configuração é feita a partir da documentação da API, que deve ser feita utilizando a especificação do OpenAPI.

Dessa forma, incentivamos a documentação das nossas APIs e a utilizamos na configuração da biblioteca. Toda a lógica de roteamento e autenticação é abstraída pelo Prodap API Gateway, assim os serviços que a utilizam precisam somente configurar as rotas, e lidar com detalhes específicos da sua implementação.

Principais Vantagens:

• Padronização do API Gateway
• Uso do padrão de design Fluent Interface para a construção do Api Gateway
• Integração com o framework Express
• Configuração do API Gateway através da documentação de API's

Instalação

Esta é uma biblioteca do Node.js disponível por meio do registro npm . Antes de instalar, baixe e instale Node.js. É necessário Node.js 12.18.2 ou superior.

Se este for um projeto totalmente novo, certifique-se de criar um package.json primeiro com o comando npm init.

A instalação é feita usando o comando npm install:

$ npm install prodap-api-gateway

Utilização

O Prodap API Gateway utiliza o padrão de projeto Builder para configuração e execução da biblioteca. Sendo assim, a biblioteca exporta o ApiGatewayBuilder, que é responsável pela configuração e inicialização do API Gateway.

Exemplo de inicialização:

import express from 'express'
import ApiGatewayBuilder from 'prodap-api-gateway'

const app = express()

new ApiGatewayBuilder(app, process.env.DIRETORIO_DOCUMENTACAO)
    .getApiGateway()
    .setup()

app.listen(3000, () => console.log('Servidor rodando...'))

O builder depende de uma instância do Express e o caminho da documentação, somente com esses dois argumentos, é possível inicializar um API Gateway, atráves dos métodos getApiGateway() e setup().

Importante: O caminho da documentação deve ser um diretório onde estão os arquivos YAML, não o caminho direto para o arquivo.

O método getApiGateway() é responsável por obter a instância construída do API Gateway. Enquanto o método setup() é responsável por registrar as rotas declaradas na documentação. Após as configurações, esses dois métodos sempre devem ser chamados e nessa mesma ordem, para que o serviço inicialize corretamente.

Feita a configuração obrigatória e inicial da biblioteca, ela disponibiliza os seguinte métodos de configuração:

• setLogLevel
• setJWTOptions
• setValidateJWTToken
• setCustomRequestHandler
• setRequestInterceptor
• setResponseInterceptor

setLogLevel

Método responsável por definir o Log Level da aplicação. Por padrão utiliza o valor 'silent'.

Valores possíveis: 'debug' | 'info' | 'warn' | 'error' | 'silent'

setJWTOptions

Método responsável por definir o service account que será utilizado na autenticação.

Obrigatório para utilizar a autenticação tipo google. Se utilizar somente os outros tipos, não é necessário a utilização dessa configuração.

setCustomRequestHandler

Método responsável por adicionar um handler para todas as requisições recebidas. Esse handler é o primeiro a ser executado. Ele funciona da mesma forma que os middlewares do Express, com excessão do quarto parâmetro que é adicionado pela biblioteca para que sejam feitas lógicas relacionadas a configuração da rota.

Esse método é útil para executar validações de token, enriquecimentos da requisição e etc.

setRequestInterceptor

Internamente, a biblioteca utiliza o pacote http-proxy-middleware para fazer o proxy das requisições, esse pacote disponibiliza esse interceptor de todas as requisições executadas.

Esse método é útil para enriquecimentos da requisição, logs e etc.

Somentes rotas configuradas com proxyHost executam esse interceptor.

Importante: Não é possível interromper a execução da requisição com esse interceptor. Caso sua lógica precise fazer isso, utilize o setCustomRequestHandler

setResponseInterceptor

Internamente, a biblioteca utiliza o pacote http-proxy-middleware para fazer o proxy das requisições, esse pacote disponibiliza esse interceptor de todas as requisições executadas.

Esse método é útil para enriquecimentos da responsta, logs e etc.

Somentes rotas configuradas com proxyHost executam esse interceptor.

Documentação com OpenAPI

A documentação da API deve seguir o schema da especificação do OpenAPI no formato YAML.

Além do roteamento, o gateway disponibiliza a documentação através do Swagger UI. Todos os arquivos YAML disponíveis no diretório informado serão lidos e criada a documentação do arquivo. Com base no nome do arquivo será disponibiliza a rota com a documentação. Por exemplo, se o nome do documento for docs.yaml, será gerada a rota /docs com a documentação.

Além dos atributos definidos na documentação do OpenAPI, utilizamos alguns atributos próprios para configuração das rotas no API Gateway. Os atributos internos são definidos dentro do schema Paths, para que seja feito individualmente para cada endpoint configurado. Os atributos são:

proxyHost

Atributo que determina o host para onde a requisição será enviada. Caso não seja declarado, a rota não será registrada no Gateway, isso pode acontecer caso queira documentar uma rota, porém, não é necessário rotear para outro serviço.

O atributo é do tipo string.

paths:
  /orders/paymentForms:
    proxyHost: https://us-east1-fabs-dev-c61d.cloudfunctions.net
    get:
      summary: Busca as formas de pagamento.
      responses:
          200:
            description: Sucesso na busca de formas de pagamento

proxyPath

Atributo que em conjunto com o proxyHost determina o endereço para onde a requisição será enviada. Caso não seja declarado, será utilizado o path da requisição original.

Esse atributo não pode ser declarado sem o proxyHost.

O atributo é do tipo string.

paths:
  /orders/paymentForms:
    proxyHost: https://us-east1-fabs-dev-c61d.cloudfunctions.net
    proxyPath: /orders/paymentForms
    get:
      summary: Busca as formas de pagamento.
      responses:
          200:
            description: Sucesso na busca de formas de pagamento

auth

Atributo que determina a forma de autenticação que será utilizada pelo Gateway. Existem 3 tipos de autenticação disponíveis: public, delegate, google.

public

Indica que o acesso a rota é público, então não será aplicada nenhuma validação.

delegate

Indica que o controle de acesso ao recurso é feito pelo próprio serviço, então o gateway apenas passa a redireciona a requisição.

google

Indica que é necessário autenticar antes de redirecionar a requisição. Esse é provavelmente o tipo de autenticação mais utilizado. Com ele, antes de requisitar o recurso, o gateway irá obter um token JWT no serviço de autenticação da Google, e irá inserí-lo no header da requisição. O token obtido serve para requisitar somente o endpoint solicitado.

Importante: O gateway faz cache dos tokens por 1 hora, logo, dentro desse prazo não será obtido um novo token, se requisitar o mesmo recurso.

Para utilizar esse tipo de autenticação, é necessário configurar o gateway através do método setJWTOptions para setar o service account que será utilizado para obter os tokens. O service account deve ter permissão de requisitar as rotas.

paths:
  /orders/paymentForms:
    proxyHost: https://us-east1-fabs-dev-c61d.cloudfunctions.net
    proxyPath: /orders/paymentForms
    auth:
      type: google
      targetAudience: https://us-east1-fabs-dev-c61d.cloudfunctions.net/orders
    get:
      summary: Busca as formas de pagamento.
      responses:
          200:
            description: Sucesso na busca de formas de pagamento

O atributo auth é do tipo objeto, e possui os atributos type e targetAudience. O atributo type é obrigatório, e deve ser um dos valores apresentados acima. O atributo targetAudience é usado somente na autenticação google. Ele é usado para definir um endereço para obter o token JWT, caso não seja informado, será usado o mesmo endereço do roteamento do gateway.

Se você utiliza Google Cloud Functions com subrotas, provavelmente precisará definir o targetAudience, pois a autenticação deve ser feita para o endereço base da Cloud Function.

Importante: Os interceptors setRequestInterceptor, setResponseInterceptor, setCustomRequestHandler executam normalmente, independente do tipo de autenticação utilizada.

Contribua