Entendendo e usando APIs REST

Há uma grande chance de você se deparar com o termo “API REST” se você pensou em obter dados de outra fonte na internet, como Twitter ou Github. Mas o que é uma API REST? O que isso pode fazer por você? como você usa isso?

Neste artigo, você aprenderá tudo o que precisa saber sobre APIs REST para poder ler as documentações da API e usá-las com eficiência.

O que é uma API REST

Digamos que você esteja tentando encontrar vídeos sobre o Batman no Youtube. Você abre o Youtube, digita “Batman” em um campo de busca, aperta enter e vê uma lista de vídeos sobre o Batman. Uma API REST funciona de maneira semelhante. Você pesquisa algo e obtém uma lista de resultados do serviço do qual está solicitando.

Uma API é uma interface de programação de aplicativos. É um conjunto de regras que permitem que os programas conversem entre si. O desenvolvedor cria a API no servidor e permite que o cliente converse com ela.

REST determina a aparência da API. Significa “Transferência de Estado Representacional”. É um conjunto de regras que os desenvolvedores seguem quando criam sua API. Uma dessas regras afirma que você deve conseguir obter um dado (chamado de recurso) ao vincular a uma URL específica.

Cada URL é chamado de solicitação , enquanto os dados enviados de volta para você são chamados de resposta .

A anatomia de um pedido

É importante saber que uma solicitação é composta de quatro coisas:

1. O ponto final
2. O método
3. Os cabeçalhos
4. Os dados (ou corpo)

O endpoint (ou rota) é o URL que você solicita. Segue esta estrutura:

 root-endpoint/ ? root-endpoint/ ? root-endpoint/ ?

O root-endpoint é o ponto de partida da API da qual você está solicitando. O root-endpoint da API do Github é https://api.github.com enquanto o root-endpoint da API do Twitter é https://api.twitter.com .

O caminho determina o recurso que você está solicitando. Pense nisso como uma secretária eletrônica que pede para você pressionar 1 para um serviço, 2 para outro serviço, 3 para outro serviço e assim por diante.

Você pode acessar caminhos da mesma forma que pode vincular partes de um site. Por exemplo, para obter uma lista de todas as postagens marcadas em “JavaScript” na Smashing Magazine, navegue até https://www.smashingmagazine.com/tag/javascript/ . https://www.smashingmagazine.com/ é o root-endpoint e /tag/javascript é o caminho.

Para entender quais caminhos estão disponíveis para você, você precisa consultar a documentação da API. Por exemplo, digamos que você queira obter uma lista de repositórios de um determinado usuário por meio da API do Github. A documentação diz para você usar o seguinte caminho para fazer isso:

 /users/:username/repos

Quaisquer dois-pontos ( : ) em um caminho denotam uma variável. Você deve substituir esses valores pelos valores reais de quando enviar sua solicitação. Nesse caso, você deve substituir :username pelo nome de usuário real do usuário que está procurando. Se eu estiver procurando minha conta do Github, substituirei :username por zellwk .

O endpoint para obter uma lista dos meus repositórios no Github é este:

 https://api.github.com/users/zellwk/repos

A parte final de um endpoint são os parâmetros de consulta . Tecnicamente, os parâmetros de consulta não fazem parte da arquitetura REST, mas você verá que muitas APIs os utilizam. Portanto, para ajudá-lo a entender completamente como ler e usar APIs, também falaremos sobre elas. Os parâmetros de consulta oferecem a opção de modificar sua solicitação com pares de valores-chave. Eles sempre começam com um ponto de interrogação ( ? ). Cada par de parâmetros é então separado com um e comercial ( & ), assim:

 ?query1=value1&query2=value2

Ao tentar obter uma lista dos repositórios de um usuário no Github, você adiciona três parâmetros possíveis à sua solicitação para modificar os resultados fornecidos a você:

Se você quiser obter uma lista dos repositórios para os quais eu enviei recentemente, você pode definir sort como push .

 https://api.github.com/users/zellwk/repos?sort=pushed

Como você sabe se esse endpoint funciona? Bem, é hora de experimentá-lo!

Testando endpoints com curl

Você pode enviar uma solicitação com qualquer linguagem de programação. Os usuários de JavaScript podem usar métodos como a API Fetch e o método Ajax do jQuery; Os usuários do Ruby podem usar a classe Net::HTTP do Ruby, os usuários do Python podem usar as solicitações do Python; e assim por diante.

Para este artigo, usaremos o utilitário de linha de comando chamado cURL. Usamos cURL porque as documentações da API são normalmente escritas com referência ao cURL. Se você entender como usar o cURL, não terá problemas para entender as documentações da API. Então, você pode facilmente realizar solicitações com seu idioma preferido.

Antes de continuar, verifique se o cURL está instalado em sua máquina. Abra seu Terminal e digite curl -version . Este comando verifica a versão do cURL que você instalou em seu sistema.

 curl --version

Se você não tiver o cURL instalado, receberá um erro de “comando não encontrado”. Se você receber esse erro, precisará instalar o curl antes de prosseguir.

Para usar cURL, digite curl , seguido pelo ponto de extremidade que está solicitando. Por exemplo, para obter o endpoint raiz do Github, digite o seguinte:

 curl https://api.github.com

Depois de pressionar enter, você deve obter uma resposta do Github que se parece com isso:

Para obter uma lista dos repositórios de um usuário, modifique o endpoint para o caminho correto, como discutimos acima. Para obter uma lista dos meus repositórios, você pode usar este comando:

 curl https://api.github.com/users/zellwk/repos

Se você deseja incluir parâmetros de consulta com cURL, certifique-se de inserir uma barra invertida ( \ ) antes do ? e = caracteres. Isso é porque ? e = são caracteres especiais na linha de comando. Você precisa usar \ antes deles para a linha de comando interpretá-los como caracteres normais:

 curl https://api.github.com/users/zellwk/repos\?sort\=pushed

Tente usar qualquer um dos comandos e execute uma solicitação! Você receberá uma resposta semelhante ao que viu com o root-endpont do Github (mas com muito mais dados).

JSON

JSON (JavaScript Object Notation) um formato comum para enviar e solicitar dados por meio de uma API REST. A resposta que o Github envia de volta para você também é formatada como JSON.

Um objeto JSON se parece com um objeto JavaScript. Em JSON, cada propriedade e valor devem ser colocados entre aspas duplas, assim:

 { "property1": "value1", "property2": "value2", "property3": "value3" }

De volta à anatomia de um pedido

Você aprendeu que uma solicitação consiste em quatro partes.

1. O ponto final
2. O método
3. Os cabeçalhos
4. Os dados (ou corpo)

Vamos passar pelo resto do que compõe um pedido.

O método

O método é o tipo de solicitação que você envia ao servidor. Você pode escolher entre esses cinco tipos abaixo:

• GET
• POST
• PUT
• PATCH
• DELETE

Esses métodos fornecem significado para a solicitação que você está fazendo. Eles são usados ​​para realizar quatro ações possíveis: Create , Read , Update e Delete (CRUD).

A API permite que você saiba qual método de solicitação usar em cada solicitação. Por exemplo, para obter uma lista dos repositórios de um usuário, você precisa de uma solicitação GET :

Uma solicitação GET é necessária para obter uma lista de repositórios de um usuário. Para criar um novo repositório Github, você precisa de uma solicitação POST :

Você pode definir o método de solicitação em cURL escrevendo -X ou --request , seguido pelo método de solicitação. Este comando abaixo tenta criar um repositório via cURL:

 curl -X POST https://api.github.com/user/repos

Tente executar esta solicitação. Você receberá uma resposta informando que a autenticação é necessária. (Mais sobre autenticação posteriormente).

 { "message": "Requires authentication", "documentation_url": "https://developer.github.com/v3" }

Os cabeçalhos

Os cabeçalhos são usados ​​para fornecer informações ao cliente e ao servidor. Ele pode ser usado para muitas finalidades, como autenticação e fornecimento de informações sobre o conteúdo do corpo. Você pode encontrar uma lista de cabeçalhos válidos na Referência de Cabeçalhos HTTP do MDN.

Cabeçalhos HTTP são pares de valor de propriedade separados por dois pontos. O exemplo abaixo mostra um cabeçalho que informa ao servidor para esperar conteúdo JSON.

 "Content-Type: application/json". Missing the opening ".

Você pode enviar cabeçalhos HTTP com curl através da opção -H ou --header . Para enviar o cabeçalho acima para a API do Github, você usa este comando:

 curl -H "Content-Type: application/json" https://api.github.com

(Observação: o cabeçalho Content-Type não é um requisito para que a API do Github funcione. Este é apenas um exemplo para ilustrar como usar um cabeçalho com cURL).

Para visualizar os cabeçalhos que você enviou, você pode usar a opção -v ou --verbose ao enviar a solicitação, assim:

 curl -H "Content-Type: application/json" https://api.github.com -v 

Aqui, * refere-se a informações adicionais fornecidas pelo cURL. > refere-se aos cabeçalhos de solicitação e < refere-se aos cabeçalhos de resposta.

Os dados (ou “corpo”)

Os dados (às vezes chamados de “corpo” ou “mensagem”) contêm informações que você deseja enviar ao servidor. Esta opção é usada apenas com solicitações POST , PUT , PATCH ou DELETE .

Para enviar dados por cURL, você pode usar a opção -d ou --data :

 curl -X POST <URL> -d property1=value1

Para enviar vários campos de dados, você pode criar várias opções -d :

 curl -X POST <URL> -d property1=value1 -d property2=value2

Se fizer sentido, você pode dividir sua solicitação em várias linhas \ para facilitar a leitura:

 curl -X POST <URL> \ -d property1=value1 \ -d property2=value2

Se você sabe como ativar um servidor, pode criar uma API e testar seus próprios dados. Se você não sabe, mas se sente corajoso o suficiente para tentar, você pode seguir este artigo para aprender a criar um servidor com Node, Express e MongoDB

Se você não quiser ativar seu servidor, você pode acessar Requestbin.com ( é grátis! ) e clicar em “criar endpoint”. Você receberá um URL que pode ser usado para testar solicitações, como https://requestb.in/1ix963n1 mostrado na imagem abaixo.

Certifique-se de criar sua própria caixa de solicitação se quiser testar sua solicitação. As caixas de solicitação só permanecem abertas por 48 horas após sua criação. Quando você ler este artigo, a lixeira que criei acima terá desaparecido há muito tempo.

Agora, tente enviar alguns dados para sua caixa de solicitação e atualize a página da web da sua caixa. Você verá alguns dados, como este:

 curl -X POST https://requestb.in/1ix963n1 \ -d property1=value1 \ -d property2=value2 

Por padrão, o cURL envia dados como se fossem enviados por “campos de formulário” em uma página. Se você deseja enviar dados JSON, precisará definir o Content-Type como application/json e precisará formatar seus dados como um objeto JSON, assim:

 curl -X POST https://requestb.in/1ix963n1 \ -H "Content-Type: application/json" \ -d '{ "property1":"value1", "property2":"value2" }' 

E isso é (quase!) tudo o que você precisa saber sobre a estrutura de uma solicitação.

Agora, lembra que quando você tentou enviar uma solicitação POST pela API do Github, você recebeu uma mensagem que diz “Requer autenticação”? Bem, isso é porque você não está autorizado a realizar a solicitação POST !

Autenticação

Você não permitiria que ninguém acessasse sua conta bancária sem sua permissão, não é? Na mesma linha de pensamento, os desenvolvedores implementam medidas para garantir que você execute ações somente quando estiver autorizado a fazê-lo. Isso impede que outras pessoas se passem por você.

Como as solicitações POST , PUT , PATCH e DELETE alteram o banco de dados, os desenvolvedores quase sempre as colocam atrás de um muro de autenticação. Em alguns casos, uma solicitação GET também requer autenticação (como quando você acessa sua conta bancária para verificar seu saldo atual, por exemplo).

Na web, existem duas maneiras principais de se autenticar:

1. Com um nome de usuário e senha (também chamado de autenticação básica)
2. Com um token secreto

O método de token secreto inclui oAuth, que permite que você se autentique em redes de mídia social como Github, Google, Twitter, Facebook, etc.

Para este artigo, você aprenderá apenas a usar a autenticação básica com um nome de usuário e uma senha. Se você estiver interessado em autenticar com oAuth, sugiro ler “O que você precisa saber sobre OAuth2 e fazer login com o Facebook” de Zack Grossbart.

Para realizar uma autenticação básica com cURL, você pode usar a opção -u , seguida de seu nome de usuário e senha, assim:

 curl -x POST -u "username:password" https://api.github.com/user/repos

Tente se autenticar com seu nome de usuário e senha na solicitação acima. Depois de obter sucesso na autenticação, você verá a mudança de resposta de "Requer autenticação" para "Problemas ao analisar JSON".

Isso ocorre porque você ainda não forneceu nenhum dado (o que é exigido por todas as solicitações POST , PUT , PATCH e DELETE ) ao servidor.

Com o conhecimento que você aprendeu até agora, você poderá editar o código acima para criar um repositório Github por meio do seu cURL. Eu deixaria você tentar você mesmo!

Agora, vamos falar sobre códigos de status HTTP e mensagens de erro.

Códigos de status HTTP e mensagens de erro

Algumas das mensagens que você recebeu anteriormente, como “Requer autenticação” e “Problemas ao analisar JSON” são mensagens de erro. Eles só aparecem quando algo está errado com o seu pedido. Os códigos de status HTTP permitem que você informe o status da resposta rapidamente. O intervalo de 100+ a 500+. Em geral, os números seguem as seguintes regras:

1. 200+ significa que a solicitação foi bem- sucedida .
2. 300+ significa que a solicitação é redirecionada para outro URL
3. 400+ significa que ocorreu um erro originário do cliente
4. 500+ significa que ocorreu um erro originário do servidor

Você pode depurar o status de uma resposta com a opção verbose ( -v ou --verbose ) ou a opção head ( -I ou --head ).

Por exemplo, se você tentou adicionar -I a uma solicitação POST sem fornecer seu nome de usuário e senha, receberá um código de status 401 (não autorizado):

Se sua solicitação for inválida porque seus dados estão errados ou ausentes, você geralmente recebe um código de status 400 (Bad Request).

Para obter mais informações sobre códigos de status HTTP específicos, você pode consultar a Referência de status HTTP do MDN.

Versões da API

Os desenvolvedores atualizam suas APIs de tempos em tempos. Às vezes, a API pode mudar tanto que o desenvolvedor decide atualizar sua API para outra versão. Se isso acontecer e seu aplicativo quebrar, geralmente é porque você escreveu um código para uma API mais antiga, mas sua solicitação aponta para a API mais recente.

Você pode solicitar uma versão específica da API de duas maneiras. A maneira que você escolhe depende de como a API é escrita.

Essas duas maneiras são:

1. Diretamente no ponto final
2. Em um cabeçalho de solicitação

O Twitter, por exemplo, usa o primeiro método. No momento da redação deste artigo, a API do Twitter está na versão 1.1, o que é evidente por meio de seu endpoint:

 https://api.twitter.com/1.1/account/settings.json

O Github, por outro lado, usa o segundo método. No momento da escrita, a API do Github está na versão 3 e você pode especificar a versão com um cabeçalho Accept :

 curl https://api.github.com -H Accept:application/vnd.github.v3+json

Empacotando

Neste artigo, você aprendeu o que é uma API REST e como usar cURL para realizar uma solicitação com os métodos GET , POST , PUT , PATCH e DELETE . Além disso, você também aprendeu como autenticar suas solicitações com a opção -u e o que significam os status HTTP.

Espero que este artigo tenha ajudado você a aprender o suficiente sobre APIs REST e que você possa usá-las fluentemente enquanto cria seus aplicativos. Sinta-se à vontade para aparecer no meu blog ou deixar seus comentários abaixo se tiver alguma dúvida.