O primeiro módulo terminou com a criação de um pedido HTTP, o seu envio, e a obtenção de uma resposta.

Faremos isto muitas mais vezes no futuro. Iremos enviar pedidos para servidores de terceiros. Faremos pedidos que eles próprios aceitam tais pedidos e devolveremos uma resposta. Iremos criar uma lógica complexa para processar pedidos.

Por conseguinte, seria bom estudar minuciosamente tudo relacionado com estes pedidos, para os analisar em pormenor. Para que não se possa apenas copiar o pedido em algum lugar e repeti-lo, mas realmente descobrir como tudo isto funciona.

Isto é o que faremos no segundo módulo. Vamos lá!

Vamos começar com a teoria.


Aprender REST API

Noções básicas do REST API

Se fez os seus trabalhos de casa no primeiro módulo e estudou a documentação, deveria ter notado a sigla API. Na verdade, é a documentação API que é a primeira coisa que os criadores devem estudar se quiserem compreender a interacção com algum serviço ou aplicação na rede.

API - Application Programming Interface (Interface de Programação de Aplicações). Esta é uma descrição das formas como o cliente e o servidor podem comunicar uns com os outros. Abrimos a documentação API e aprendemos a partir daí como obter os dados necessários do servidor.

Queremos sempre que esta interacção seja simples e compreensível. Isto simplifica a tarefa tanto para os programadores (não há necessidade de reinventar a roda ao conceber um novo serviço) como para os utilizadores (um serviço é muito mais fácil de aprender se funcionar com o mesmo princípio que os serviços anteriormente familiares). E aqui vale a pena recordar um novo termo - REST.

REST - acrónimo de Representational State Transfer (Transferência do Estado Representativo). Pode não soar muito claro, mas simplesmente colocado, REST é um estilo de interacção (troca de informação) entre um cliente e um servidor.

Isto não é um conjunto rígido de regras e requisitos. REST não obriga ao uso de qualquer linguagem de programação em particular, nem vincula as mãos com directrizes estritas. REST é chamado um estilo arquitectónico e define 6 princípios que uma arquitectura de sistema deve cumprir.

Consequentemente, uma API desenvolvida tendo em conta os princípios de REST é chamada uma API REST, e as próprias aplicações são chamadas RESTful

Iremos criar precisamente tais aplicações RESTful, pelo que vale a pena discutir os princípios que elas cumprirão de imediato.

  1. Modelo Cliente-Servidor. O princípio define a separação entre o cliente e o servidor, a diferenciação das suas necessidades. O cliente não tem de se preocupar com a forma como os dados são armazenados, o principal é que estes sejam emitidos mediante pedido. Por sua vez, o servidor não se preocupa com o que o cliente vai fazer com estes dados, como processá-los e exibi-los posteriormente. Isto permite-lhes desenvolverem-se independentemente uns dos outros, e melhora a escalabilidade do sistema.
  2. Apatridia. Este princípio significa que o servidor não deve "pensar" a resposta com base na experiência anterior com este cliente. Qualquer pedido é feito de modo a conter toda a informação necessária para o seu processamento, independentemente de pedidos anteriores.
  3. Caching. Para minimizar os dados transmitidos, existe um mecanismo de cache. Por exemplo, se um logotipo for exibido em alguma página, então não faz sentido solicitá-lo ao servidor de cada vez. Não muda com tanta frequência, será suficiente obtê-lo uma vez e guardá-lo no computador do cliente, na cache. Mas se precisarmos de obter informações sobre a velocidade actual do carro, então a cache não ajudará de forma alguma. Este princípio determina que os dados transmitidos pelo servidor devem ser designados como "cacheable" ou não.
  4. Interface uniforme. O princípio define um formato único de interacção cliente-servidor. A estrutura de todos os pedidos deve ser a mesma. Os dados devem ser enviados na mesma forma, independentemente de quem os solicite.
  5. Sistema em camadas. O cliente e o servidor não comunicam necessariamente directamente. A transmissão de dados pode passar por vários nós intermédios. Neste caso, o sistema é concebido de modo a que nem o cliente nem o servidor saibam se estão a interagir com a aplicação final ou com um nó intermédio. Isto permite equilibrar a carga nos servidores, aumentar a escalabilidade.
  6. Código a pedido (opcional). O único princípio que não é obrigatório. De acordo com ele, o cliente pode expandir a sua funcionalidade descarregando código executável do servidor (por exemplo, scripts). Neste caso, o código deve ser executado apenas a pedido.

Não tem demasiada teoria?

Vamos pôr isto em prática.

Criar um pedido de API

Vamos abrir o AppMaster, criar um pedido API usando-o, e obter uma melhor compreensão de como este pedido funciona.


Os pedidos de API são criados na secção "Business logic", no separador "External API Requests" (Pedidos de API externos).

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


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

Vamos lidar com os dados que realmente importam.

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


URL - Uniform Resource Locator (localizador uniforme de recursos). 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.

Referindo-se aos dados no seu endereço, indicamos também o método (pode também 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 estes 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-se 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. 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 para todos os artigos é o mesmo - https://appmaster.io/en/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/ru/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. 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. 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 destinavam a uma pessoa, e foi isso que indicámos nos parâmetros do pedido.

Outra opção é uma chave de acesso. Poderá ter utilizado esta opção no módulo 1 quando se referiu 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. 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 do pedido. Os pedidos GET normalmente passam sem eles, mas se quisermos enviar alguns dados para o servidor, enviar um pedido POST ou PUT, então estes dados são colocados no corpo do 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.

A Resposta que vem do servidor funciona quase de acordo com o mesmo esquema. Por razões óbvias, não tem parâmetros de pedido, mas os Cabeçalhos e o Corpo estão incluídos na resposta (embora possam estar vazios).

Uma diferença importante é o estado da resposta.

Código de estado. Vem na primeira linha da resposta do servidor. O estado é um número de três dígitos (o próprio código), seguido por uma frase que o explica.

É pelo código de estado que se pode saber sobre os resultados do pedido e compreender que acções devem ser tomadas a seguir.

Todos os códigos de estado possíveis estão divididos em 5 classes. O primeiro dígito do código determina a pertença a uma determinada classe. Vamos decompô-los.

1xx - códigos de informação. Relatar o progresso do pedido. Na prática real, eles são raramente utilizados.

2xx - códigos de sucesso. Informam que tudo está em ordem e que o pedido foi concluído com sucesso. Em resposta a um pedido de GET, esperamos normalmente receber um código de 200 (OK). Um pedido PUT bem sucedido envia um código 201 (Created).

3xx - redirecciona. Indicar que o pedido deve ser enviado para um endereço diferente. Um exemplo é o código 301 (Movido Permanentemente), indicando que os dados requeridos estão agora num novo endereço (o novo endereço em si é passado no cabeçalho Localização).

4xx - códigos de erro do cliente. O mais famoso deles - 404 (Não Encontrado), informa que não há dados necessários no endereço especificado. Outros casos comuns: 400 (Mau Pedido, erro de sintaxe no pedido), 401 (Não autorizado, autenticação necessária para acesso), 403 (Proibido, acesso negado).

5xx - códigos de erro do servidor. Reportar um erro no lado do servidor. A título de exemplo: 500 (Internal Server Error, qualquer erro incompreensível que não possa ser atribuído ao código conhecido), 503 (Serviço Indisponível, o servidor é temporariamente incapaz de processar o pedido por razões técnicas)

Neste ponto, podemos assumir que lidámos com as informações básicas para compreender o REST API e a estrutura dos pedidos e respostas HTTP. Resta esclarecer apenas um ponto - tipos de dados. Se já tentou criar o seu pedido de API no AppMaster, provavelmente reparou que todos os dados (em parâmetros, em cabeçalhos, em corpo) lhe pedem para especificar não só o nome, mas também o tipo de dados.


É geralmente bastante óbvio para um humano como trabalhar com os dados, pois existe um certo contexto. Suponhamos que sabemos que 2 + 2 = 4. Supomos que estes são números e que o resultado da adição será outro número.

Mas podem não ser números, mas sim dados textuais. Então o resultado da sua adição poderia ser a concatenação de cordas e 2 + 2 transformar-se-ia em "22". Aqui, para que o computador não tenha de pensar em nada, há uma indicação exacta do tipo de dados. E, ao mesmo tempo, outras tarefas estão a ser resolvidas. Por exemplo, é fornecida protecção contra a introdução de dados incorrectos; inicialmente, não há oportunidade de registar um endereço de correio electrónico no campo destinado à introdução de números de telefone.

Existem muitos tipos de dados diferentes, agora vamos considerar os mais básicos, e em outros módulos do curso vamos familiarizar-nos com o resto.

String - Tipo de dados String, texto simples, sem formatação especial.

Inteiro - Tipo de dados Inteiro. Pode ser utilizado para contadores ou cálculos em que não são necessários números fracionários.

Flutuador - Número de ponto flutuante. É utilizado onde é necessária maior precisão e os valores inteiros não são suficientes.

Uma questão lógica pode surgir aqui. E porque não usar sempre Float, porque precisamos então do Integer? Mas uma maior precisão requer mais recursos. Para alguns cálculos pequenos isto pode ser completamente invisível, mas no caso de grandes quantidades de dados, a utilização de um tipo de dados razoável pode reduzir significativamente os requisitos de potência de computação e espaço em disco.

Booleano - tipo de dados booleanos. O tipo de dados mais simples. É necessário um de dois valores, que são escritos como Verdadeiro ou Falso. A designação pode muitas vezes ser vista sob a forma de 1 (verdadeiro) e 0 (falso).


Trabalho de casa

Repetir os pedidos do trabalho de casa para o primeiro módulo, criando-os no AppMaster, na secção de Pedidos API Externos.

  1. Cria um pedido ao BoredAPI. Especificar pelo menos 5 parâmetros diferentes da documentação. Submeter vários pedidos diferentes, especificando apenas os parâmetros requeridos.
  2. Criar um pedido ao Alphavantage. Utilizar os parâmetros para obter as taxas das diferentes moedas em relação umas às outras.