Estrutura de API

Em termos simples, uma API é como uma ponte entre dois sistemas diferentes. Ela permite que um sistema (como um aplicativo ou site) se comunique com outro sistema (a nossa plataforma por exemplo), trocando informações de forma rápida e eficiente.

Estrutura Básica de uma API

Para utilizar uma API (fazer uma requisição) é preciso conhecer sua estrutura básica.

Endpoint

Método HTTP

Autenticação

Payloads

{
  url: 'https://{{backendURL}}/api/messages/send',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{connection_token}}'
  },
  data : {
    "number": "{{number}}",
    "openTicket": "0",
    "queueId": "0",
    "body": "{mensagem}"
  }
};

1. Endpoint

O endpoint é a URL (endereço) que você usa para acessar a API.

Ou seja, toda API (assim como um site) está localizada em um endereço (url). O endpoint é o nome dado a esse endereço.

Cada funcionalidade da API terá seu próprio endpoint.

Por exemplo, se você quiser enviar uma mensagem em nosso sistema, deve acessar o endpoint: https://{BACKEND_URL}/api/messages/send

E se você deseja monitorar o status de suas conexão, vai realizar uma chamada para o endpoint: https://{BACKEND_URL}/api/whatsapp-status

Esse endpoint seria o local em que a API vai "ouvir" as requisições. Quando você enviar informações (dados) para a API através de uma solicitação, ela vai receber e processar esses dados para realizar a ação desejada.

2. Métodos HTTP

Os métodos HTTP são os comandos que você usa para interagir com a API. Os mais comuns são:

• GET: Usado para buscar ou obter dados.
• POST: Usado para enviar ou criar novos dados.
• PUT: Usado para atualizar dados existentes.
• DELETE: Usado para excluir dados.

Mas não se preocupe!

O programador da API é quem define qual método utilizar em cada caso.

Portanto, para fazer uma requisição de uma API, se preocupe apenas em seguir o método recomendado pela documentação.

Se o método indicado for POST, use POST. Se for GET, use GET, e assim por diante.

Simples assim!

3. Autenticação

A autenticação é utilizada para garantir segurança à API.

Nem toda API requer autenticação, mas a que exige pode ser por diferentes razões:

• Garantir que apenas usuários autorizados possam acessar determinadas funcionalidades
• Identificar quem está realizando a requisição, para fornecer a resposta adequada.

Em nossas APIs, solicitamos o envio do TOKEN da conexão.

Esse TOKEN nos permite validar sua autorização para utilizar a API e também nos informa qual conexão você deseja usar ao acessar o endpoint.

Por exemplo, ao utilizar a API de envio de mensagens, o Token informado será utilizado para identificar a conexão correspondente, que será a responsável pelo envio da mensagem.

4. Payloads

Os payloads são os dados enviados e recebidos durante a comunicação entre os sistemas via API.”

Request Payload (Payload de Requisição)

São os dados enviados para a API.

Algumas APIs exigem que dados específicos sejam enviados para garantir que a requisição funcione corretamente.

Por exemplo: ao utilizar uma API para enviar uma mensagem de texto em nossa plataforma, você precisa fornecer dados (payload) dizendo qual será a mensagem

Outras APIs não precisam que

Porém, outras APIs não exigem envio de dados, como a API de status de conexão. Ao consultar seu endpoint, ela já sabe o que fazer e apenas retorna uma resposta (payload de resposta).

Response Payload (Payload de Resposta)

São os dados retornados pela API.

Através desses dados, você pode processar as informações recebidas, como confirmar o sucesso da operação, obter resultados de uma consulta ou receber dados atualizados. O payload de resposta é a chave para entender o que aconteceu após a requisição ser realizada.

Os payloads são enviados e recebidos em formato JSON.

Formato JSON

JavaScript Object Notation (JSON) é um formato leve, de fácil leitura e escrita, usado para troca de dados entre sistemas (compatível com diferentes linguagens de programação).

O JSON pode ser lido por máquinas e facilmente interpretado por humanos, devido a sua simplicidade.

ESTRUTURA DO JSON

Objetos: Representados por um par de chaves { }, os objetos no JSON podem conter pares de chave-valor, seguindo a seguinte sintaxe:

{
  "chave": "valor"
}

Havendo mais propriedades desse objeto, podemos separar esses pares com vírgula, por exemplo:

{
  "nome": "João",
  "idade": 30,
  "casado": true
}

Arrays: Representados por colchetes [ ], os arrays são listas ordenadas de valores. Eles podem conter objetos, números, strings ou outros arrays. Exemplo:

{
  "nomes": ["João", "Maria", "José"]
}

Vamos agora para um exemplo mais completo de uma estrutura JSON

{
  "pessoa": {
    "nome": "João",
    "idade": 30,
    "casado": true,
    "filhos": [
      {
        "nome": "Ana",
        "idade": 5
      },
      {
        "nome": "Carlos",
        "idade": 3
      }
    ]
  }
}

• Objeto: O JSON acima tem um objeto principal representado por { }, com a chave "pessoa".
• Chaves e Valores: Dentro do objeto "pessoa", temos várias chaves como "nome", "idade", e "casado", e seus respectivos valores.
• Arrays: A chave "filhos" contém um array [ ] com dois objetos representando os filhos, cada um com nome e idade.

Essa estrutura simples e organizada facilita tanto a leitura humana quanto a manipulação por sistemas.