Cliente REST#

O bloco Cliente REST é destinado à execução de requisições HTTP.

Ele suporta os principais métodos de requisições HTTP, permitindo que o Usuário interaja com APIs (incluindo APIs RESTful), utilizando:

GET: Recuperação de dados.
POST: Envio de dados para criar um novo recurso.
PUT: Atualização de um recurso existente.
DELETE: Exclusão de um recurso.
OPTIONS: Obtenção de informações sobre os métodos suportados para o recurso especificado.

Deve-se considerar que o bloco Executar Requisição HTTP no Sherpa Designer está obsoleto (em vez dele, recomenda-se usar o bloco Cliente REST, pois é mais funcional). Mas, considerando que muitos Usuários ainda utilizam o bloco Executar Requisição HTTP, os desenvolvedores o deixaram disponível para garantir a compatibilidade retroativa.

Os Usuários podem configurar flexivelmente os cabeçalhos das requisições, adicionar cookies e também passar parâmetros na URL. Essas funcionalidades podem ser úteis para:

Especificar o formato dos dados, como `Content-Type` ou `Accept`.
Configurar a autorização, utilizando cabeçalhos do tipo `Authorization`, permitindo trabalhar com OAuth, chaves de API ou autenticação básica.
Passar parâmetros adicionais nas requisições, o que pode ser útil para filtrar ou classificar dados.

Ao utilizar os métodos POST e PUT, o Cliente REST permite que o Usuário envie dados no corpo da requisição. Ele pode:

Enviar dados no formato JSON, XML ou outros tipos.
Fazer upload de arquivos, permitindo integração com serviços que exigem a transferência de conteúdo (por exemplo, imagens ou documentos).

Isso é especialmente útil para trabalhar com APIs que aceitam estruturas de dados complexas.

Além disso, o bloco Cliente REST oferece funcionalidades para:

Configuração de tempo limite (timeout): O Usuário pode definir quanto tempo sua requisição aguardará uma resposta do servidor antes de ser cancelada.
Tratamento de erros: por padrão, o bloco retorna um erro se o servidor responde com um status diferente de sucesso (2xx), mas o Usuário pode configurá-lo para continuar executando ações dependendo dos códigos de erro.

Para garantir segurança ou contornar restrições de rede, o bloco Cliente REST suporta o uso de servidores proxy. O Usuário pode configurar:

Endereço do proxy,
Porta,
Autorização necessária para acessar o proxy.

Isso é útil em casos onde é necessário interagir com uma API que está disponível apenas através de conexões intermediárias especificadas.

Exemplo de uso: Yandex Speech API#

Suponha que o Usuário queira converter um arquivo de áudio no formato .wav em texto, utilizando a Yandex Speech API. Com o bloco Cliente REST, isso pode ser feito da seguinte forma:

1. Configuração da requisição:

URL: `https://speechiy.yandex.net/apis/speech/v1/stt:recognize\`

Método: `POST`

Cabeçalhos:

Autorização: Api-Key <seu_chave>

Content-Type: application/octet-stream

2. Envio de dados: No corpo da requisição, o Usuário fará o upload do arquivo de áudio .wav.

3. Tratamento da resposta: O Usuário receberá o resultado em texto, que pode ser utilizado no aplicativo.

Exemplo de uso do Cliente REST com um array de campos do tipo `multipart/form-data`#

Ao trabalhar com APIs que exigem o envio de dados no formato `multipart/form-data`, é importante configurar corretamente o cliente. Esse formato é frequentemente utilizado para upload de arquivos, bem como para envio de dados de formulários.

Suponha que o Usuário tenha uma API que permite fazer upload de arquivos e enviar dados textuais adicionais. Para isso, é necessário utilizar o formato `multipart/form-data`.

Por exemplo, suponha que o Usuário queira enviar uma imagem e uma descrição para o servidor.

Exemplo de preenchimento dos campos do bloco Cliente REST:

Campo	Exemplo de preenchimento	Comentário
URL	http://www.example.com/api/upload	Link para a API que aceita arquivos enviados.
Tipo de requisição	POST	Estamos enviando dados para o servidor, portanto usamos o método POST.
Codificação	UTF-8	Codificação padrão para páginas Web.
Cabeçalho Accept	application/json	Especifique qual tipo de resposta você espera do servidor.
Parâmetros	{"description"="Descrição do arquivo enviado"}	Especifique dados adicionais que você deseja enviar junto com o arquivo.
Cabeçalhos	{"Authorization"="Bearer SeuTokenDeAcesso"}	Especifique o cabeçalho de autorização.
Cookies		Lista de cookies, se necessário para a requisição. Se o servidor exigir autorização via cookies, adicione-os aqui, obtendo-os do bloco "Obter Cookies".
Arquivos	@{"file"="C:\caminho\para\seu\arquivo.jpg"}	Especifique o arquivo que deseja enviar. Use o caminho completo para o arquivo.
Conteúdo da requisição		Não preencha este campo ao usar `multipart/form-data`, pois os dados são gerados automaticamente.
Cabeçalho Content-Type	multipart/form-data	Especifique o tipo de conteúdo que corresponde aos dados enviados.
Tempo de espera	30	Defina o tempo de espera em segundos para a resposta do servidor.
Resultado		O campo será preenchido automaticamente ao executar a requisição.
Código de resposta		O campo será preenchido automaticamente ao executar a requisição.
Cabeçalhos de resposta		O campo será preenchido automaticamente ao executar a requisição.
Cookies		O campo será preenchido automaticamente ao executar a requisição.
Nível de mensagens	Padrão	Selecione o nível de mensagens que será exibido durante a execução do bloco.
Texto do erro		O campo será preenchido automaticamente em caso de erros.

Categorias de erros#

Os erros que podem ocorrer ao trabalhar com a API podem ser divididos em várias categorias:

Erro de rede: Problemas de rede, como falta de conexão, timeouts e outras falhas no nível do protocolo de transporte.
Erros do cliente (4xx): Esses são erros relacionados a solicitações enviadas ao servidor. Eles indicam que algo está errado com a solicitação ou os parâmetros. Exemplos:

`400 Bad Request`: Solicitação inválida, erro de sintaxe.

`401 Unauthorized`: Acesso negado, autorização necessária.

`404 Not Found`: O recurso solicitado não foi encontrado.

Erros do servidor (5xx): Esses erros indicam problemas do lado do servidor. Exemplos:

`500 Internal Server Error`: Erro interno do servidor, erro genérico sem especificação.

`503 Service Unavailable`: Serviço temporariamente indisponível, pode estar sobrecarregado ou em manutenção.

Tratamento de erros no Cliente REST#

Para um trabalho eficaz com erros no Cliente REST, vários métodos estão disponíveis:

Estratégia de tratamento: Configuração da lógica de tratamento de erros com base no status da resposta do servidor. Por exemplo:

Para códigos 4xx, você pode exibir uma notificação ao usuário sobre a solicitação inválida.

Para códigos 5xx, pode-se implementar a lógica de nova tentativa com alguns atrasos.

Personalização das mensagens de erro: Você pode configurar e exibir mensagens mais compreensíveis para os usuários, fornecendo detalhes sobre o erro. Isso é importante para melhorar a usabilidade.

O registro de erros é uma parte importante da depuração e diagnóstico. Você pode configurar o registro de erros para:

Gravar respostas com erro em um arquivo ou banco de dados para análise posterior.
Incluir informações adicionais sobre o contexto do erro (por exemplo, URL da solicitação, cabeçalhos, corpo da solicitação) para facilitar o diagnóstico.

Em casos em que a solicitação não pode ser concluída devido a erros temporários de rede ou servidor:

Defina timeouts para as solicitações, para que não fiquem pendentes por tempo indeterminado.
Implemente um mecanismo de tentativas com atraso exponencial para erros temporários. Por exemplo, se o servidor estiver temporariamente indisponível (código 503), faz sentido tentar repetir a solicitação após alguns segundos.

Além do tratamento de erros no código, é útil estudar a estrutura dos códigos de erro padrão, para entender como eles são agrupados e o que significam. O uso de códigos padrão ajudará você a identificar mais rapidamente a causa do problema e resolvê-lo.