APIs REST
No IBM® App Connect Enterprise, uma API REST é uma aplicação especializada que pode ser usada para disponibilizar integrações como um serviço web RESTful, que pode ser chamado por clientes HTTP. IBM App Connect Enterprise também oferece um conjunto de nós REST, que você pode usar para interagir de forma síncrona ou assíncrona com APIs REST externas.
Uma API REST descreve um conjunto de recursos e um conjunto de operações que podem ser chamadas nesses recursos. As operações em uma API REST podem ser chamadas de qualquer cliente HTTP, incluindo o código JavaScript do lado do cliente que está sendo executado em um navegador da Web. Você também pode usar os nós REST do IBM App Connect Enterprise para chamar e interagir com APIs REST externas. Para obter informações sobre como usar esses nós REST, consulte Conectando a APIs REST externas.
A API REST possui um caminho base, que é semelhante a uma raiz de contexto. Todos os recursos em uma API REST são definidos com relação ao seu caminho de base. O caminho de base pode ser usado para fornecer isolamento entre diferentes APIs REST, bem como isolamento entre diferentes versões da mesma API REST. Por exemplo, uma API REST pode ser construída para expor um banco de dados do cliente sobre HTTP. O caminho base para a primeira versão dessa API REST poderia ser /customerdb/v1, enquanto que o caminho base para a segunda versão daquela API REST poderia ser /customerdb/v2.
| Recurso | Descrição |
|---|---|
| /customers | Todos os clientes no banco de dados |
| /customers/12345 | Cliente #12345 |
| /customers/12345/orders | Todos os pedidos do cliente #12345 |
| /customers/12345/orders/67890 | Pedido #67890 do cliente #12345 |
Cada recurso na API REST possui um conjunto de operações que podem ser chamadas por um cliente HTTP. Uma operação em uma API REST possui um nome e um método HTTP (como GET, POST ou DELETE). O nome da operação deve ser exclusivo em todos os recursos nessa API REST. Além disso, um único recurso pode ter apenas uma operação que está definida para um método HTTP específico. A combinação do caminho e método HTTP que são especificados pelo cliente HTTP que está fazendo a solicitação é utilizada para identificar o recurso e a operação que está sendo chamada.
| Método HTTP | Nome da Operação | Descrição |
|---|---|---|
| GET | getCustomer | Recupera os detalhes do cliente do banco de dados. |
| OP_VEND | updateCustomer | Atualiza os detalhes do cliente no banco de dados. |
| DELETE | deleteCustomer | Exclui o cliente do banco de dados. |
Para chamar a operação updateCustomer, o cliente HTTP faz uma solicitação PUT HTTP para /customerdb/v1/customers/12345
- Parâmetros de caminho
- Pode ser utilizado para identificar um recurso específico. O valor do parâmetro é transmitido para a operação pelo cliente HTTP como parte da variável da URL e o valor do parâmetro é extraído do caminho para uso na operação. Os parâmetros de caminho são indicados utilizando a sintaxe
{paramName}no caminho para o recurso. Por exemplo, o ID do cliente pode ser transmitido como um parâmetro de caminho denominado customerId:/customers/{customerId} - Parâmetros de consulta
- O valor de um parâmetro de consulta é transmitido para a operação pelo cliente HTTP como um par de valores de chave na sequência de consulta no término da URL. Como exemplo, os parâmetros de consulta podem ser utilizados para transmitir um número mínimo e máximo de resultados que devem ser retornados por uma operação específica:
/customers?min=5&max=20 - Parâmetros de cabeçalho
- O cliente HTTP pode transmitir parâmetros de cabeçalho para uma operação ao inclui-los como cabeçalhos HTTP na solicitação de HTTP. Como exemplo, os parâmetros de cabeçalho podem ser utilizados para transmitir um identificador exclusivo que identifica o cliente HTTP que está chamando a operação:
Api-Client-Id: ff6e2c5d-42d5-4026-8f7f-d1e56da7f777
Uma única operação pode definir e aceitar diversos parâmetros de todos os três tipos. Além disso, dependendo do método HTTP da operação, a operação poderá aceitar dados do cliente HTTP no corpo da solicitação. As operações também podem enviar dados de volta para o cliente HTTP no corpo de resposta. As APIs REST no IBM App Connect Enterprise estão configuradas por padrão para processar dados JSON, mas é possível processar dados em vários formatos.
Cada operação da API REST deve ser implementada como um subfluxo. Um subfluxo de uma operação possui um único nó de entrada e um único nó de saída. O responsável pela implementação da operação pode criar o subfluxo para a operação utilizando todos os nós de fluxo de mensagens padrão disponíveis no IBM App Connect Enterprise.
Quando um cliente HTTP faz uma chamada para uma operação em uma API REST que é implementada em um servidor de integração, a solicitação será processada e roteada automaticamente para o nó de entrada no subfluxo correspondente dessa operação. Quando esse subfluxo propaga uma mensagem para seu nó de saída, a mensagem será roteada automaticamente de volta para o cliente HTTP. O autor da API REST não precisa fazer nada para manipular o transporte HTTP.
Para criar uma API REST no IBM App Connect Enterprise, você pode definir os modelos, recursos e operações do zero ou usar o IBM App Connect Enterprise Toolkit para importar um documento Swagger ou um documento OpenAPI 3.0 que descreva os recursos e operações desejados na API REST. Para obter mais informações, consulte Desenvolvendo soluções de integração usando APIs REST e Criando uma API REST.
Depois de criar e implantar uma API REST, você pode enviar (exportar) a definição da API REST para IBM API Connect. Você pode enviar uma ou mais APIs REST para IBM API Connect usando a interface de usuário da web IBM App Connect Enterprise ou o mqsipushapis comando. Para obter mais informações, consulte “Envio de APIs REST para IBM API Connect ”.