Vamos andar pelos conceitos básicos da API, � medida que abordamos alguns casos de uso diário.
Observação: O guia a seguir usa a API REST para GitHub.com.
-
Use
http(s)://[hostname]/api/v3
para acessar a API para GitHub Enterprise Server. -
O guia especifica nomes de usuário e repositórios que podem não existir em your GitHub Enterprise Server instance. Talvez você precise usar nomes diferentes para ver a saída semelhante.
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 de fazê-lo 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,
> "node_id": "MDQ6VXNlcjI=",
> "avatar_url": "https://avatars.githubusercontent.com/u/2?v=4",
> "gravatar_id": "",
> "url": "https://api.github.com/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/2 200
> server: GitHub.com
> date: Thu, 08 Jul 2021 07:04:08 GMT
> content-type: application/json; charset=utf-8
> cache-control: public, max-age=60, s-maxage=60
> vary: Accept, Accept-Encoding, Accept, X-Requested-With
> etag: W/"61e964bf6efa3bc3f9e8549e56d4db6e0911d8fa20fcd8ab9d88f13d513f26f0"
> last-modified: Fri, 01 Nov 2019 21:56:00 GMT
> x-github-media-type: github.v3; format=json
> access-control-expose-headers: ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, Deprecation, Sunset
> access-control-allow-origin: *
> strict-transport-security: max-age=31536000; includeSubdomains; preload
> x-frame-options: deny
> x-content-type-options: nosniff
> x-xss-protection: 0
> referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
> content-security-policy: default-src 'none'
> x-ratelimit-limit: 60
> x-ratelimit-remaining: 53
> x-ratelimit-reset: 1625731053
> x-ratelimit-resource: core
> x-ratelimit-used: 7
> accept-ranges: bytes
> content-length: 1305
> x-github-request-id: 9F60:7019:ACC5CD5:B03C931:60E6A368
>
> {
> "login": "defunkt",
> "id": 2,
> "node_id": "MDQ6VXNlcjI=",
> "avatar_url": "https://avatars.githubusercontent.com/u/2?v=4",
> "gravatar_id": "",
> "url": "https://api.github.com/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 degithub.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
eX-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. De fato, fazer qualquer coisa interessante com a GitHub Enterprise Server API exige autenticação.
Usar tokens de acesso pessoal
A maneira melhor e mais fácil de efetuar a autenticação com a GitHub Enterprise Server API é 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 "your_username:$token"
e configurar uma variável para token
para evitar deixar seu token no histórico do shell, o que deve ser evitado.
$ curl -i -u your_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
Quando autenticado corretamente, você pode aproveitar as permissões associadas � sua conta em your GitHub Enterprise Server instance. 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 do seu perfil de usuário. Por exemplo, você verá um objeto plano
na resposta, que fornece 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 GitHub Enterprise Server API envolverá algum nível de informação do repositório. Podemos OBTER
informações do repositório da mesma forma que obtemos ass 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
public_repo
escopo retorna uma resposta que inclui todos os repositórios públicos aos quais temos acesso para ver em your GitHub Enterprise Server instance. - Um token com
repositório
escopo retorna uma resposta que inclui todos públicos, repositórios privados ou internos aos quais temos acesso para ver em your GitHub Enterprise Server instance.
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
GitHub Enterprise Server A API é compatível com a criação de novos repositórios também. 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 privado para o nosso blogue (a ser servido no GitHub Pages, talvez). Embora o blogue seja público, 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/2 404
> {
> "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 GitHub Enterprise Server retorna 404
neste caso, como se dissesse "não podemos nem 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/2 200
> ...
> 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/2 201
> 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/2 200
> etag: W/"61e964bf6efa3bc3f9e8549e56d4db6e0911d8fa20fcd8ab9d88f13d513f26f0"
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: "61e964bf6efa3bc3f9e8549e56d4db6e0911d8fa20fcd8ab9d88f13d513f26f0"' \
$ http(s)://[hostname]/api/v3/users/defunkt
> HTTP/2 304
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.
Agora você sabe o básico da API 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!