Primeiros passos com a API REST

Vamos andar pelos conceitos básicos da API, à medida que abordamos alguns casos de uso diário.

Visão Geral

A maioria dos aplicativos usará uma biblioteca de segurança existente na linguagem da sua escolha, mas é importante familiarizar-se primeiro com os métodos HTTP e de API subjacentes.

Não há uma maneira mais fácil dar os primeiros passos do que através do cURL.

Hello World

Vamos começar testando a nossa configuração. Abra uma instrução de comando e digite o comando a seguir:

$ curl https://api.github.com/zen

> Keep it logically awesome.

A resposta será uma seleção aleatória das nossas filosofias de design.

Em seguida, vamos fazer GET para o perfil de GitHub de Chris Wanstrath:

# GET /users/defunkt
$ curl https://api.github.com/users/defunkt

> {
>   "login": "defunkt",
>   "id": 2,
>   "url": "http(s)://[hostname]/api/v3/users/defunkt",
>   "html_url": "https://github.com/defunkt",
>   ...
> }

Mmmmm, tem sabor de JSON. Vamos adicionar o sinalizador -i para incluir cabeçalhos:

$ curl -i https://api.github.com/users/defunkt

> HTTP/1.1 200 OK
> Server: GitHub.com
> Date: Sun, 11 Nov 2012 18:43:28 GMT
> Content-Type: application/json; charset=utf-8
> Status: 200 OK
> ETag: "bfd85cbf23ac0b0c8a29bee02e7117c6"
> X-RateLimit-Limit: 60
> X-RateLimit-Remaining: 57
> X-RateLimit-Reset: 1352660008
> X-GitHub-Media-Type: github.v3
> Vary: Accept
> Cache-Control: public, max-age=60, s-maxage=60
> X-Content-Type-Options: nosniff
> Content-Length: 692
> Last-Modified: Tue, 30 Oct 2012 18:58:42 GMT

> {
>   "login": "defunkt",
>   "id": 2,
>   "url": "http(s)://[hostname]/api/v3/users/defunkt",
>   "html_url": "https://github.com/defunkt",
>   ...
> }

Há algumas partes interessantes nos cabeçalhos da resposta. Como esperado, o Content-Type é application/json.

Qualquer cabeçalho que começar com X - é um cabeçalho personalizado e não está incluído nas especificações de HTTP. Por exemplo:

• X-GitHub-Media-Type tem um valor de github.v3. Isso nos permite saber o tipo de mídia para a resposta. Tipos de mídia nos ajudaram a criar uma versão da nossa saída na API v3. Vamos falar mais sobre isso mais adiante.
• Anote os cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining. Este par de cabeçalhos indica quantas solicitações um cliente pode fazer em um período de tempo consecutivo (geralmente, uma hora) e quantas dessas solicitações o cliente já gastou.

Autenticação

Clientes sem autenticação podem fazer 60 solicitações por hora. Para obter mais solicitações por hora, precisaremos efetuar a autenticação. Na verdade, fazer qualquer coisa interessante com a API de GitHub Enterprise Server requer autenticação.

Usar tokens de acesso pessoal

A melhor e mais fácil maneira de efetuar a autenticação com a API de GitHub Enterprise Server é usando a Autenticação Básica por meio dos tokens do OAuth. Os tokens do OAuth incluem os tokens de acesso pessoal.

Use um sinalizador -u para definir o seu nome de usuário:

$ curl -i -u your_username http(s)://[hostname]/api/v3/users/octocat

Quando solicitado, você poderá inserir o seu token OAuth, mas nós recomendamos que você configure uma variável para isso:

Você pode usar -u "username:$token" e configurar uma variável para o token para evitar deixar seu token no histórico do shell, o que deve ser evitado.

$ curl -i -u username:$token http(s)://[hostname]/api/v3/users/octocat

Ao efetuar a autenticação, você deverá ver seu limite de taxa disparado para 5.000 slicitações por hora, conforme indicado no cabeçalho X-RateLimit-Limit. Além de fornecer mais chamadas por hora, a autenticação permite que você leia e escreva informações privadas usando a API.

Você pode facilmente criar um token de acesso pessoal usando a sua página de configurações de tokens de acesso pessoal:

Obtenha seu próprio perfil de usuário

Após efetuar a autenticação corretamente, você poderá aproveitar as permissões associadas à sua conta de GitHub Enterprise Server. Por exemplo, tente obter

$ curl -i -u your_username:your_token http(s)://[hostname]/api/v3/user

> {
>   ...
>   "plan": {
>     "space": 2516582,
>    "collaborators": 10,
>    "private_repos": 20,
>    "name": "medium"
>  }
>   ...
> }

Desta vez, além do mesmo conjunto de informações públicas que recuperamos para @defunkt anteriormente, você também deverá ver as informações não públicas para o seu perfil de usuário. Por exemplo, você verá um objeto de plano na resposta que dá detalhes sobre o plano de GitHub Enterprise Server para a conta.

Usar tokens do OAuth para aplicativos

Os aplicativos que precisam ler ou escrever informações privadas usando a API em nome de outro usuário devem usar o OAuth.

O OAuth usa tokens. Os tokens fornecem dois grandes recursos:

• Acesso revogável: os usuários podem revogar a autorização a aplicativos de terceiros a qualquer momento
• Acesso limitado: os usuários podem revisar o acesso específico que um token fornecerá antes de autorizar um aplicativo de terceiros

Os tokens devem ser criados por meio de um fluxo web. Um aplicativo envia os usuários para GitHub Enterprise Server para efetuar o login. GitHub Enterprise Server apresenta uma caixa de diálogo, que indica o nome do aplicativo, bem como o nível de acesso que o aplicativo tem uma após ser autorizado pelo usuário. Depois que um usuário autoriza o acesso, GitHub Enterprise Server redireciona o usuário de volta para o aplicativo:

Trate os tokens de OAuth como senhas! Não compartilhe-os com outros usuários ou armazene-os em lugares inseguros. Os tokens nestes exemplos são falsos e os nomes foram alterados para proteger os inocentes.

Agora que demos um jeito de fazer chamadas autenticadas, vamos seguir em frente para a API de repositórios.

Repositórios

Quase qualquer uso significativo da API de GitHub Enterprise Server envolverá algum nível de informação do repositório. Podemos OBTER informações do repositório da mesma forma que obtemos os informações do usuário anteriormente:

$ curl -i http(s)://[hostname]/api/v3/repos/twbs/bootstrap

Da mesma forma, podemos visualizar repositórios para o usuário autenticado:

$ curl -i -H "Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4" \
    http(s)://[hostname]/api/v3/user/repos

Ou podemos listar repositórios para outro usuário:

$ curl -i http(s)://[hostname]/api/v3/users/octocat/repos

Ou podemos listar repositórios para uma organização:

$ curl -i http(s)://[hostname]/api/v3/orgs/octo-org/repos

As informações retornadas dessas chamadas dependerão de quais escopos o nosso token terá quando efetuarmos a autenticação:

• Um token com o escopo public_repo retorna uma resposta que inclui todos os repositórios públicos aos quais temos acesso para ver no github.com.
• Um token com o escopo repositório retorna uma resposta que inclui todos os repositórios públicos e privados aos quais temos acesso para ver no github.com.

Conforme a documentação indica, estes métodos usam um parâmetro tipo que pode filtrar os repositórios retornados com base no tipo de acesso que o usuário possui para o repositório. Desta forma, podemos buscar apenas repositórios de propriedade direta, repositórios da organização ou repositórios nos quais o usuário colabora por meio de uma equipe.

$ curl -i "http(s)://[hostname]/api/v3/users/octocat/repos?type=owner"

Neste exemplo, pegamos apenas os repositórios que o octocat possui, não os nos quais ela colabora. Observe a URL entre aspas acima. Dependendo de sua configuração do shell, a cURL às vezes exigirá uma URL entre aspas ou irá ignorar a string de consulta.

Criar um repositório

Buscar informações para repositórios existentes é um caso de uso comum, mas a API de GitHub Enterprise Server também é compatível com a criação de novos repositórios. Para criar um repositório, precisamos POST alguns JSON que contém informações e opções de configuração.

$ curl -i -H "Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4" \
    -d '{ \
        "name": "blog", \
        "auto_init": true, \
        "private": true, \
        "gitignore_template": "nanoc" \
      }' \
    http(s)://[hostname]/api/v3/user/repos

Neste pequeno exemplo, criamos um novo repositório para o nosso blogue (a ser servido no GitHub Pages, talvez). Embora o blogue seja público, nós tornamos o repositório privado. Nesta etapa única, também vamos inicializá-lo com um LEIAME e um nanoc-flavored .gitignore template.

O repositório resultante será encontrado em https://github.com/<your_username>/blog. Para criar um repositório sob uma organização da qual você é proprietário, altere apenas o método API de /user/repos para /orgs/<org_name>/repos.

Em seguida, vamos buscar nosso repositório recém-criado:

$ curl -i http(s)://[hostname]/api/v3/repos/pengwynn/blog

> HTTP/1.1 404 Not Found

> {
>    "message": "Not Found"
> }

Ah não! Onde ele foi parar? Uma vez que criamos o repositório como privado, precisamos autenticá-lo para poder vê-lo. Se você é um usuário de HTTP, você pode esperar um 403. Como não queremos vazar informações sobre repositórios privados, a API do GitHub Enterprise Server retorna um 404 neste caso, como se dissesse "não podemos confirmar nem negar a existência deste repositório".

Problemas

A interface de usuário para problemas no GitHub Enterprise Server visa a fornecer fluxo de trabalho "apenas suficiente" enquanto permanece fora de seu caminho. Com GitHub Enterprise Server API de problemas, você pode extrair dados ou criar problemas a partir de outras ferramentas para criar um fluxo de trabalho que funcione para a sua equipe.

Assim como o github.com, a API fornece alguns métodos para exibir problemas para o usuário autenticado. Para ver todos os seus problemas, chame GET /issues:

$ curl -i -H "Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4" \
    http(s)://[hostname]/api/v3/issues

Para obter apenas os problemas sob uma das suas organizações de GitHub Enterprise Server, chame GET /orgs/<org>/issues:

$ curl -i -H "Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4" \
    http(s)://[hostname]/api/v3/orgs/rails/issues

Também podemos obter todos os problemas sob um único repositório:

$ curl -i http(s)://[hostname]/api/v3/repos/rails/rails/issues

Paginação

Um projeto do tamanho de Rails tem milhares de problemas. Vamos precisar paginar, fazendo várias chamadas de API para obter os dados. Vamos repetir essa última chamada, anotando os cabeçalhos de resposta:

$ curl -i http(s)://[hostname]/api/v3/repos/rails/rails/issues

> HTTP/1.1 200 OK

> ...
> Link: <http(s)://[hostname]/api/v3/repositories/8514/issues?page=2>; rel="next", <http(s)://[hostname]/api/v3/repositories/8514/issues?page=30>; rel="last"
> ...

O cabeçalho de Link fornece uma forma de resposta para vincular os recursos externos, nesse caso, as páginas de dados adicionais. Como nossa chamada encontrou mais de trinta problemas (o tamanho da página padrão), a API nos informa onde podemos encontrar a próxima página e a última página de resultados.

Criar um problema

Agora que vimos como paginar listas de problemas, vamos criar um problema a partir da API.

Para criar um problema, precisamos estar autenticados. Portanto, passaremos um token do OAuth no cabeçalho. Além disso, passaremos o título, texto, e as etiquetas no texto do JSON para o caminho /issues abaixo do repositório em que queremos criar o problema:

$ curl -i -H 'Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4' \
$    -d '{ \
$         "title": "New logo", \
$         "body": "We should have one", \
$         "labels": ["design"] \
$       }' \
$    http(s)://[hostname]/api/v3/repos/pengwynn/api-sandbox/issues

> HTTP/1.1 201 Created
> Location: http(s)://[hostname]/api/v3/repos/pengwynn/api-sandbox/issues/17
> X-RateLimit-Limit: 5000

> {
>   "pull_request": {
>     "patch_url": null,
>     "html_url": null,
>     "diff_url": null
>   },
>   "created_at": "2012-11-14T15:25:33Z",
>   "comments": 0,
>   "milestone": null,
>   "title": "New logo",
>   "body": "We should have one",
>   "user": {
>     "login": "pengwynn",
>     "gravatar_id": "7e19cd5486b5d6dc1ef90e671ba52ae0",
>     "avatar_url": "https://secure.gravatar.com/avatar/7e19cd5486b5d6dc1ef90e671ba52ae0?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png",
>     "id": 865,
>     "url": "http(s)://[hostname]/api/v3/users/pengwynn"
>   },
>   "closed_at": null,
>   "updated_at": "2012-11-14T15:25:33Z",
>   "number": 17,
>   "closed_by": null,
>   "html_url": "https://github.com/pengwynn/api-sandbox/issues/17",
>   "labels": [
>     {
>       "color": "ededed",
>       "name": "design",
>       "url": "http(s)://[hostname]/api/v3/repos/pengwynn/api-sandbox/labels/design"
>     }
>   ],
>   "id": 8356941,
>   "assignee": null,
>   "state": "open",
>   "url": "http(s)://[hostname]/api/v3/repos/pengwynn/api-sandbox/issues/17"
> }

A resposta nos dá algumas indicações sobre a questão recém-criada, tanto no cabeçalho de resposta da Localização quanto no campo url da resposta do JSON.

Solicitações condicionais

Uma grande parte de ser um bom cidadão da API é respeitar os limites de taxa por meio de armazenamento de informações que não mudaram. A API é compatível com solicitações condicionais e ajuda você a fazer a coisa certa. Considere a primeira chamada de que fizemos para obter o perfil de defunkt:

$ curl -i http(s)://[hostname]/api/v3/users/defunkt

> HTTP/1.1 200 OK
> ETag: "bfd85cbf23ac0b0c8a29bee02e7117c6"

Além do texto do JSON, anote o código de status de HTTP de 200 e o cabeçalho ETag. O ETag é uma impressão digital da resposta. Se passarmos isso em chamadas subsequentes, podemos dizer à API para nos dar o recurso novamente, somente se tiver mudado:

$ curl -i -H 'If-None-Match: "bfd85cbf23ac0b0c8a29bee02e7117c6"' \
$    http(s)://[hostname]/api/v3/users/defunkt

> HTTP/1.1 304 Not Modified

O status 304 indica que o recurso não mudou desde a última vez que pedimos e a resposta não conterá texto. Como um bônus, as respostas de 304 não contam contra o seu limite de taxa.

Nossa! Agora você conhece os princípios básicos da API de GitHub Enterprise Server!

• Autenticação básica do & OAuth
• Buscar e criar de repositórios e problemas
• Solicitações condicionais

Continue aprendendo com o próximo guia da API Princípios básicos da autenticação!