Pedido API externo

Não há demasiada teoria?

Vamos pôr isto em prática. Vamos abrir o AppMaster, criar um pedido API usando-o, e obter uma melhor compreensão de como este pedido funciona.

Criação de Pedido Externo de API

Os pedidos API são criados na secção "Lógica empresarial", no separador "Pedidos API externos".

É altura de clicar em "+ Nova Solicitação de API".

O nome e a descrição podem ser definidos para qualquer coisa, são apenas para nosso uso pessoal.

Vamos lidar com os dados que realmente importam.

O mínimo necessário para criar um pedido é especificar o seu Método e endereço (URL). Comecemos com o último.

URL

URL - Uniform Resource Locator. Um endereço dado a um determinado recurso na Internet. A versão mais familiar de tal recurso é uma página HTML - introduzimos o seu URL na barra de endereços do navegador e abrimos o site desejado. Ao mesmo tempo, o recurso em si pode ser qualquer coisa, uma imagem, um vídeo, um conjunto de dados. O principal é que este recurso tem um ponteiro específico - um URL para o qual se pode enviar um pedido para obter este recurso.

Métodos

Referindo-se aos dados no seu endereço, indicamos também o método (também se pode dizer o tipo) do pedido, ou seja, indicamos o que realmente precisa de ser feito com estes dados.

Quando enviamos pedidos para a tarefa do primeiro módulo, recebemos dados. Este é o método GET. Este método é o mais óbvio e também o único método necessário. Portanto, mesmo que não o especificássemos explicitamente, continuava a presumir-se, por defeito, que este era o GET.

Vamos ver que outros métodos existem.

O próprio padrão HTTP não limita o número de métodos que podem ser utilizados. Ao mesmo tempo, apenas alguns dos métodos mais padronizados são ainda utilizados para manter a compatibilidade. Existem 5 métodos diferentes que podem ser utilizados nos pedidos API AppMaster.

GET. Já está tratado. O método solicita o fornecimento de um recurso, e recebe dados.

POST. Para obter dados de algum lugar, é preciso primeiro colocar esses dados lá. O método POST faz exactamente isso. Envia os dados para o servidor, cria um recurso.

PUT. Semelhante ao método POST, mas a sua função é actualizar os dados. Não cria novos dados, mas substitui os dados existentes, actualiza-os.

DELETE. Como o nome sugere, apaga os dados.

PATCH. O método é semelhante ao PUT, mas é utilizado para actualizar parcialmente os dados, em vez de os substituir totalmente. Por exemplo, utilizando o método PATCH, pode alterar o título de um artigo, ou alterar o valor de algum parâmetro.

É importante considerar o facto de que o servidor não é obrigado a fazer exactamente o que está especificado no método. Podemos enviar o endereço de alguma página com o método DELETE, mas isto não significa que o servidor irá realmente apagá-lo. Mas, puramente teoricamente, ele pode fazê-lo com o comando GET. Ou não alterar nada, mas ao mesmo tempo enviar dados em resposta ao POST. Só porque o programador o configurou dessa forma.

É aqui que entra em jogo o REST, que diz que é altura de concordar com a observância da ordem, parar a confusão e fazer exactamente o que está indicado no método. No mínimo, esta deve ser a tarefa principal (embora não necessariamente a única). Por exemplo, ao transferir o conteúdo de um artigo utilizando o método GET, pode ao mesmo tempo aumentar o contador do número dos seus pontos de vista em 1.

Assim, descobrimos onde se encontram os dados e o que pode ser feito com eles. Vamos mais longe, vamos ver que outros componentes o pedido pode ter.

URL Params

URL Params. Há situações em que só conhecemos parte do URL. Um exemplo são os artigos no website Appmaster.io. O endereço de partida de todos os artigos é o mesmo - https://appmaster.io/blog/. Mas então cada artigo tem o seu próprio título e, consequentemente, a sua própria parte individual para a indicação exacta deste artigo em particular.

Em tal situação, são utilizados os URL Params. Prescrevemos a parte geral imediatamente, e deixamos o resto para ser decidido no processo. Como resultado, o URL é escrito no formulário https://appmaster.io/blog/:id/.

A parte conhecida é escrita tal como está, e a parte variável é colocada após o sinal ":". O nome desta parte variável (já sem ":") é acrescentado à lista de parâmetros. Neste caso, pode haver várias partes variáveis, e a sua localização está em qualquer parte do URL.

Consulta de Parâmetros

Consultar Parames. Lembra-se quando enviámos um pedido ao boredapi.com no primeiro módulo? E, para além do endereço, foram prescritos dados adicionais. Esse foi o Query Params.

São escritos após o URL e são separados dele por um sinal "?". O nome do parâmetro, o sinal "=" e o valor do parâmetro em si são indicados. Se vários parâmetros forem utilizados ao mesmo tempo, são separados pelo sinal "&".

No entanto, ao especificar parâmetros no AppMaster, não é necessário pensar nas regras de pedido. Tudo será formatado automaticamente de forma adequada. Basta especificar o nome do parâmetro em si e adicioná-lo à lista.

Os parâmetros de consulta são utilizados quando a fonte de dados é a mesma, mas os dados em si podem ser diferentes. Por exemplo, Boredapi continha uma enorme lista de coisas a fazer. Mas só estávamos interessados naquelas que se destinam a uma pessoa e foi isso que especificámos nos parâmetros do pedido.

Outro caso de utilização é o de limitar a quantidade de dados. Por exemplo, podíamos aceder a alguma lista, mas solicitar apenas as 5 primeiras entradas da mesma. Esta quantidade pode também ser um parâmetro de consulta.

Outra opção é uma chave de acesso. Poderá ter utilizado esta opção no módulo 1 quando se referir a Alphavantage. Os dados só poderiam ser obtidos após registo e envio de uma chave pessoal nos parâmetros de pedido.

Preste atenção às páginas que visitar na Internet, provavelmente também encontrará vários parâmetros nelas. Por exemplo, abra a página meteorológica de Ventusky.com, nos parâmetros de consulta são enviados valores geográficos de latitude e longitude.

Cabeçalhos

Cabeçalhos. Pedir cabeçalhos. Normalmente os cabeçalhos contêm informações de serviço sobre o pedido (meta-informação). Os cabeçalhos permitem ao servidor obter mais informações sobre o cliente que está a solicitar os dados. Os cabeçalhos podem conter informação sobre qual o browser que está a ser utilizado, qual a codificação que se espera da resposta, em que língua, a hora exacta do pedido, e mais. No caso de acesso a dados protegidos, os cabeçalhos podem conter uma chave de autorização.

Na maioria dos casos, os cabeçalhos são opcionais. Mesmo no primeiro módulo, já fizemos um pedido em que não especificámos quaisquer cabeçalhos (embora isto não signifique que o pedido tenha sido realmente enviado sem eles).

Corpo

Corpo. Pedido de corpo. Os pedidos de GET normalmente dispensam, mas se quisermos enviar alguns dados para o servidor, enviar um pedido POST ou PUT, então estes dados são colocados no organismo de pedido. Ao mesmo tempo, é possível colocar dados de qualquer complexidade no corpo do pedido, por exemplo, enviar um ficheiro de vídeo, e não estar limitado a um número ou a uma cadeia de texto.