Integração REST

A cVortex oferece suporte à integração com APIs que aderem ao padrãoRESTful, o que implica que a comunicação com essas APIs segue os princípios do protocolo HTTP. A plataforma pode empregar os métodos HTTP, tais como GET , POST , PUT e DELETE , para interagir com os recursos disponibilizados pelas APIs. A seguir, são apresentados os principais aspectos do padrão de API REST suportado pelo cVortex:

Autenticação JWT (JSON Web Token)

O padrão JWT é amplamente adotado em APIs RESTful para realizar autenticação e solicitação de forma eficaz e segura, oferecendo uma solução simplificada para a troca de informações de autenticação entre o cliente e o servidor.

O processo típico de autenticação usando JWT segue estas etapas:

1. O cliente registra suas credenciais de autenticação, incluindo URL de autenticação, nome de usuário e senha.
2. A plataforma cVortex verifica a certificação das credenciais e, se for válida, obtém um token da API externa.
3. A plataforma armazena o token JWT, geralmente em um cookie ou em armazenamento local, para utilizá-lo em futuras alterações.
4. Em cada solicitação subsequente para acessar recursos protegidos da API externa, a plataforma envia o token JWT como parte da requisição.
5. Uma API externa valida o token JWT, verifica sua assinatura e integridade. Se todas as verificações forem corretas, a API concede acesso ao recurso solicitado.

Isso cria um fluxo seguro e eficiente de autenticação e autorização entre o cliente e o servidor, permitindo o acesso controlado a recursos protegidos da API externa.

Requisições REST

Uma solicitação REST é composta por vários componentes que permitem que um cliente se comunique com um servidor e solicite ações ou recursos específicos. Abaixo, estão os principais elementos de uma solicitação REST:

Método HTTP: O método HTTP define a ação a ser realizada no recurso solicitado. Os métodos suportados na plataforma são:

• GET (Obter) : Este método é utilizado para recuperar informações ou recursos existentes do servidor. Quando é feita uma solicitação GET, o servidor retorna os dados solicitados, se disponíveis, sem modificação ou com influência sobre o recurso. É uma operação de leitura e não deve causar alterações no estado do servidor.
• POST (Enviar) : O método POST é utilizado para criar um novo recurso no servidor. Quando uma solicitação POST é enviada, os dados são enviados ao servidor e um novo recurso é criado com base nessas informações. É uma operação de escrita e geralmente é usada para enviar dados que serão armazenados no servidor, como criar um novo registro em um banco de dados.
• PUT (Substituir) : O método PUT é usado para atualizar um recurso existente no servidor. Quando uma solicitação PUT é feita, os dados enviados substituem integralmente os dados existentes do recurso identificado pela URL da solicitação. Se o recurso não existir, ele poderá ser criado com os dados fornecidos.
• DELETE (Excluir) : Este método é usado para remover um recurso existente do servidor. Quando uma solicitação DELETE é feita, o servidor exclui o recurso identificado pela URL da solicitação. Após a conclusão bem-sucedida, o recurso não estará mais disponível no servidor.

Esses métodos HTTP definem a natureza da operação que o cliente deseja executar no servidor, tornando as deficiências REST adequadas para criar, recuperar, atualizar e excluir informações em sistemas web de maneira padronizada e eficaz.

URL base

Uma URL base (Base URL) serve para identificar o ponto de partida comum para todas as requisições em uma API ou sistema. Ela geralmente inclui o esquema (como "http://" ou "https://"), o domínio (ou endereço IP) do servidor e, opcionalmente, um caminho do recurso e parâmetros de consulta. Essa URL fornece o contexto principal para todas as conexões subsequentes dentro do sistema, permitindo que o cliente e o servidor se comuniquem de forma eficaz.

http://api.tenant.com/v1/

Cabeçalhos

Os cabeçalhos HTTP são componentes essenciais de uma requisição HTTP e contêm informações adicionais que ajudam a definir como a requisição deve ser processada pelo servidor e como a resposta deve ser tratada pelo cliente. Alguns títulos comuns incluem:

• Content-Type (Tipo de Conteúdo) : Este cabeçalho especifica o tipo de conteúdo que está sendo enviado no corpo da requisição. Isso é importante para que o servidor saiba como interpretar os dados enviados pelo cliente. Por exemplo, "Content-Type: application/json" indica que o corpo da requisição contém dados no formato JSON.
• Accept (Aceitar) : O cabeçalho Accept é usado para indicar o tipo de resposta que o cliente espera receber do servidor. Ele define os tipos de mídia (por exemplo, JSON, XML) que o cliente aceita. Por exemplo, "Accept: application/json" significa que o cliente prefere receber uma resposta no formato JSON, se disponível.

Esses títulos, entre outros, desempenham um papel fundamental na comunicação entre cliente e servidor, garantindo que ambas as partes estejam alinhadas quanto ao tipo de conteúdo enviado e esperado. Isso facilita a interoperabilidade e o processamento correto das configurações e respostas HTTP.

Corpo (Carga Útil):

O corpo da requisição é utilizado para transmitir dados adicionais, como configurações de formulário ou informações no formato JSON/XML. Nem todas as requisições incluem um corpo, mas é comum encontrá-lo em solicitações do tipo POST, PUT e PATCH, onde os dados a serem enviados para o servidor são incorporados no corpo da requisição.

Parâmetros de Consulta:

As parâmetros de consulta são usadas para transmitir dados na URL durante uma requisição GET. Eles são especificados após o símbolo de interrogação (?) na URL e consistem em pares de chave-valor separados por um e comercial (&). Essas cláusulas são uma forma de fornecer informações adicionais ao servidor sobre a solicitação e são frequentemente usadas para filtrar, classificar ou paginar os resultados de uma consulta.

Exemplo de API REST suportada pelo cVortex

Endpoint para autenticação JWT

Demonstração de como deve ser um endpoint de autenticação, pois informações de usuário e senha são enviadas no corpo da requisição e é esperado que não haja resposta do JWT que será utilizado subsequentemente:

// URL: http://api.tenant.com/v1/auth
// Método HTTP: POST
// Headers
{    "Content-type": "application/json"
}
// Request Body:
{    "username": "tenant-admin",    "password": "*******"
}
// Response
{    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Recuperando uma lista de leads

Nesse exemplo, uma requisição é enviada para a URL "https://api.tenant.com/v1/leads" usando o método GET. O corpo da requisição não possui informações e nenhum retorno da requisição é obtido uma lista de leads.

"http"::"/leads/
// Método HTTP":"GET
// Headers"{
   "Content-type":"application/json"
}:{
   
}[
   {
      "id":1,
      "nome":"John",
      "telefone":"(99)99999-9999",
      "email":"example@email.com",
      "plano_ativo":true
   },
   {
      "id":2,
      "nome":"Mary",
      "telefone":"(99)99999-9999",
      "email":"example@email.com",
      "plano_ativo":true
   },
   {
      "id":3,
      "nome":"Peter",
      "telefone":"(99)99999-9999",
      "plano_ativo":false
   }
]

Atualizando dados de leads

Nesse exemplo, uma requisição é enviada para uma URL "https://api.tenant.com/v1/lead/${leadID}" usando o método PUT, onde ${leadID} é uma variável. O corpo da requisição possui as informações que serão atualizadas no lead correspondente ao ${leadID} informado, o retorno é um código e mensagem de sucesso.

// Base URL: http://api.tenant.com/v1/
// Endpoint: /lead/${leadId}
// Método HTTP: PUT
// Headers
{    "Content-type": "application/json"
}
// Request Body:
{    "nome": "Peter M.",    "telefone": "(34)99999-9999"
}
// Response
{    "status": 200,    "message": "Registro atualizado com sucesso"
}

Quer saber mais sobre o formato JSON? Clique aqui.