Importantes Headers

Três headers estão presentes em toda resposta da API GitHub que traz informações sobre a API do GitHub. Eles são X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.

O header do X-GitHub-Media-Type contém informações importantes quando você está recuperando o conteúdo do text ou blob da API.

Quando você faz um request para a API GitHub você pode especificar o formato você deseja trabalhar por meio do Accept header que é enviado no seu request.

Hypermedia da API

Execute curl -i https://api.github.com para ver os endpoint e então escolhermos um que queremos utilizar. Os endpoint estão mapeados entre as chaves.

{

  “current_user_url”: “https://api.github.com/user”,

…

“organization_url”: “https://api.github.com/orgs/{org}”,

…

}

Para utilizar um endpoint basta substituir os parâmetros que são mutáveis por seus parâmetros. Por exemplo, vamos pegar o endpoint https://api.github.com/orgs/{org} e substituir o parâmetro {org} por github.

Execute o comando curl https://api.github.com/orgs/github

{

  “login”: “github”,

  “id”: 9919,

  “node_id”: “MDEyOk9yZ2FuaXphdGlvbjk5MTk=”,

  “url”: “https://api.github.com/orgs/github”,

…

“description”: “How people build software.”,

  “name”: “GitHub”,

  “company”: null,

  “blog”: “https://github.com/about”,

  “location”: “San Francisco, CA”,

  “email”: “support@github.com”,

…

“created_at”: “2008-05-11T04:37:31Z”,

“updated_at”: “2019-10-15T14:32:53Z”,

“type”: “Organization”

}

Com este comando podemos ver algumas informações sobre o GitHub. Descobrimos o blog da empresa https://github.com/about.

Nós também podemos ver onde a empresa está localizada San Francisco, CA, há também a data de criação da empresa 11/05/2008. Mas olhando no blog da empresa a data de lançamento foi em Abril de 2008 https://github.blog/2008-04-10-we-launched/.

Todas essas informações são públicas na API. Mas a API do GitHub tem muito mais recursos para usuários autenticados.

Por exemplo, para você usar a API para escrever dados dentro do GitHub, você precisa saber como se faz a autenticação na API.

Autenticação

Há dois caminhos para o pedido de autenticação na API do GitHub: por usuário e senha (HTTP Basic) e OAuth tokens.

Autenticação por Usuário e Senha

Você pode acessar o conteúdo protegido do GitHub por meio de usuário e senha. Autenticação por usuário funciona utilizando o HTTP Basic authentication que é suportado pela flag -u no cURL. Autenticação é sinônimo de utilizar usuário e senha.

Digite o comando curl -u blackzig https://api.github.com/rate_limit, blackzig é o usuário que eu utilizo, coloque no lugar o seu usuário. O sistema vai pedir para você digitar a senha.

Enter host password for user ‘blackzig’:

{

…

“rate”: {

    “limit”: 5000,

    “remaining”: 5000,

    “reset”: 1578957730

  }

}

As informações apresentadas são os limites da sua conta, estas informações só podem ser acessadas via autenticação.

Benefícios da Autenticação por meio de Usuário

A maioria das bibliotecas de clientes tem suporte para a autenticação HTTP Basic. Você pode até escrever seu próprio cliente de autenticação utilizando o HTTP que irá funcionar.

Desvantagens da Autenticação por meio de Usuário

Há muitas razões que faz com que o método de usuário e senha sejam errados para ter acesso a API do GitHub.

HTTP Basic é um protocolo velho que não foi pensado para o uso em web services. Não é possível especificar certos recursos de web service se o usuário tem que se autenticar com usuário/senha.

Se você usar o usuário e senha para acessar o conteúdo da API do GitHub a partir de um celular, e depois acessar a API via laptop, você não tem como bloquear o acesso de um sem bloquear o outro.

HTTP Basic authentication não suporta extensões para a autenticação que são feitas hoje (authentication flow) https://community.axway.com/s/article/Authentication-Flows-1529678102660.

Muitos serviços modernos suportam o two-factor authentication e não tem como fazer isto sem mudar o HTTP do cliente (por exemplo, web browsers) ou pelo menos agir como o esperado (o browser repete o request).

Todos esses problemas são resolvidos (ou pelo menos melhorado) com o Oauth.