Recursos na API REST

Versão da API

Os recursos disponíveis podem variar entre as versões da API REST. Você deve usar o cabeçalho X-GitHub-Api-Version para especificar uma versão da API. Para obter mais informações, confira "Versões da API".

Esquema

Todo o acesso à API é feito por HTTPS e acessada de https://api.github.com. Todos os dados são enviados e recebidos como JSON.

$ curl -I https://api.github.com/users/octocat/orgs

> HTTP/2 200
> Server: nginx
> Date: Fri, 12 Oct 2012 23:33:14 GMT
> Content-Type: application/json; charset=utf-8
> ETag: "a00049ba79152d03380c34652f2cb612"
> X-GitHub-Media-Type: github.v3
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4987
> x-ratelimit-reset: 1350085394
> Content-Length: 5
> Cache-Control: max-age=0, private, must-revalidate
> X-Content-Type-Options: nosniff

Os campos em branco são incluídos como null em vez de serem omitidos.

Todos os timestamps são retornados no formato UTC, ISO 8601:

YYYY-MM-DDTHH:MM:SSZ

Para obter mais informações sobre fusos horários em carimbos de data/hora, confira esta seção.

Apresentações resumidas

Ao buscar uma lista de recursos, a resposta inclui um subconjunto dos atributos para esse recurso. Esta é a representação "resumo" do recurso. (Alguns atributos são computacionalmente caros para a API fornecer. Por razões de desempenho, a representação resumida exclui esses atributos. Para obter esses atributos, busque a representação "detalhada".)

Exemplo: ao receber uma lista de repositórios, você recebe a representação resumida de cada repositório. Aqui, buscamos a lista de repositórios pertencentes à organização octokit:

GET /orgs/octokit/repos

Representações detalhadas

Ao buscar um recurso individual, a resposta normalmente inclui todos os atributos para esse recurso. Esta é a representação "detalhada" do recurso. (Observe que a autorização às vezes influencia a quantidade de detalhes incluídos na representação.)

Exemplo: ao receber um repositório individual, você recebe a representação detalhada do repositório. Aqui, buscamos o repositório octokit/octokit.rb:

GET /repos/octokit/octokit.rb

A documentação fornece um exemplo de resposta para cada método da API. A resposta de exemplo ilustra todos os atributos que retornados por esse método.

Autenticação

O GitHub recomenda que você crie um token para autenticar na API REST. Para obter mais informações sobre qual tipo de token criar, confira "Autenticação na API REST".

Você pode autenticar sua solicitação enviando um token no cabeçalho Authorization da solicitação:

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"

Se você tentar usar um ponto de extremidade da API REST sem um token ou com um token que não tenha permissões suficientes, receberá uma resposta 404 Not Found ou 403 Forbidden.

OAuth2 key/secret

curl -u my_client_id:my_client_secret 'https://api.github.com/user/repos'

O uso de client_id e client_secret não fará a autenticação como usuário, apenas identificará seu OAuth app para aumentar o limite de taxa. As permissões só são concedidas a usuários, não aplicativos, e você só obterá dados que um usuário não autenticado visualizaria. Não vaze o segredo do cliente do OAuth app para os usuários.

Para obter mais informações sobre limites de taxa para OAuth apps, confira "Limites de taxa para a API REST".

Falha no limite de login

A autenticação com credenciais inválidas retornará 401 Unauthorized:

$ curl -I https://api.github.com --header "Authorization: Bearer INVALID-TOKEN"
> HTTP/2 401

> {
>   "message": "Bad credentials",
>   "documentation_url": "https://docs.github.com/rest"
> }

Após detectar várias solicitações com credenciais inválidas em um curto período de tempo, a API rejeitará temporariamente todas as tentativas de autenticação para esse usuário (incluindo aquelas com credenciais válidas) com 403 Forbidden:

> HTTP/2 403
> {
>   "message": "Maximum number of login attempts exceeded. Please try again later.",
>   "documentation_url": "https://docs.github.com/rest"
> }

Parâmetros

Muitos métodos de API tomam parâmetros opcionais. Para solicitações tipo GET, todos os parâmetros não especificados como um segmento no caminho podem ser passados como um parâmetro de string de consulta de HTTP:

curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed"

Neste exemplo, os valores 'vmg' e 'redcarpet' são fornecidos para os parâmetros :owner e :repo no caminho, enquanto :state é passado na cadeia de caracteres de consulta.

Para as solicitações POST, PATCH, PUT e DELETE, os parâmetros não incluídos na URL devem ser codificados como JSON com um tipo de conteúdo de 'application/json':

curl -i --header "Authorization: Bearer YOUR-TOKEN" -d '{"scopes":["repo_deployment"]}' https://api.github.com/authorizations

Ponto de extremidade raiz

Você pode emitir uma solicitação GET para o ponto de extremidade de raiz para obter todas as categorias do ponto de extremidade com a qual a API REST é compatível:

$ curl 
-u USERNAME:TOKEN https://api.github.com

IDs de nós globais do GraphQL

Confira o guia sobre "Usar IDs de nó globais" para obter informações detalhadas sobre como localizar node_ids por meio da API REST e usá-los em operações do GraphQL.

Verbos HTTP

Sempre que possível, a API REST do GitHub Enterprise Cloud procura usar verbos HTTP apropriados para cada ação. Observe que os verbos HTTP diferenciam maiúsculas de minúsculas.

Verbo	Descrição
HEAD	Pode ser emitido contra qualquer recurso para obter apenas as informações de cabeçalho HTTP.
GET	Usado para recuperar recursos.
POST	Usado para criar recursos.
PATCH	Usado para atualizar recursos com dados parciais do JSON. Por exemplo, um recurso de problema tem os atributos title e body. Uma solicitação de PATCH pode aceitar um ou mais dos atributos para atualizar o recurso.
PUT	Usado para substituir recursos ou coleções. Para solicitações PUT sem atributo body, defina o cabeçalho Content-Length como zero.
DELETE	Usado para excluir recursos.

Hipermídia

Todos os recursos podem ter uma ou mais propriedades *_url vinculando outros recursos. Estes tem o objetivo de fornecer URLs explícitas para que os clientes API apropriados não precisem construir URLs por conta própria. É altamente recomendável que os clientes da API os utilizem. Fazer isso tornará as futuras atualizações da API mais fáceis para os desenvolvedores. Espera-se que todas as URLs sejam modelos de URI RFC 6570 adequados.

Em seguida, você pode expandir esses modelos usando algo como ogem uri_template:

>> tmpl = URITemplate.new('/notifications{?since,all,participating}')
>> tmpl.expand
=> "/notifications"

>> tmpl.expand all: 1
=> "/notifications?all=1"

>> tmpl.expand all: 1, participating: 1
=> "/notifications?all=1&participating=1"

Agente de usuário obrigatório

Todas as solicitações de API PRECISAM incluir um cabeçalho User-Agent válido. Solicitações sem cabeçalho User-Agent serão rejeitadas. Pedimos que use seu nome de usuário de GitHub Enterprise Cloud ou o nome de seu aplicativo, para o valor do cabeçalho User-Agent. Isso nos permite entrar em contato com você, em caso de problemas.

Veja um exemplo:

User-Agent: Awesome-Octocat-App

curl envia um cabeçalho de User-Agent válido por padrão. Se você fornecer um cabeçalho de User-Agent inválido via curl (ou por meio de um cliente alternativo), receberá uma resposta 403 Forbidden:

$ curl -IH 'User-Agent: ' https://api.github.com/meta
> HTTP/1.0 403 Forbidden
> Connection: close
> Content-Type: text/html

> Request forbidden by administrative rules.
> Please make sure your request has a User-Agent header.
> Check  for other possible causes.

Compartilhamento de recursos entre origens

A API é compatível com Compartilhamento de Recursos de Origens Cruzadas (CORS) para solicitações de AJAX de qualquer origem. Você pode ler a Recomendação CORS W3C ou esta introdução do Guia de Segurança HTML 5.

Aqui está uma solicitação de exemplo enviada de um navegador atingindo http://example.com:

$ curl -I https://api.github.com -H "Origin: http://example.com"
HTTP/2 302
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval

A solicitação pré-voo de CORS se parece com isso:

$ curl -I https://api.github.com -H "Origin: http://example.com" -X OPTIONS
HTTP/2 204
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, X-GitHub-OTP, X-Requested-With
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: ETag, Link, X-GitHub-OTP, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
Access-Control-Max-Age: 86400

Chamadas de retorno do JSON-P

Você pode enviar um parâmetro ?callback para qualquer chamada de GET para envolver os resultados em uma função JSON. Isso geralmente é usado quando os navegadores desejam incorporar o conteúdo do GitHub Enterprise Cloud em páginas da Web, contornando problemas entre domínios. A resposta inclui a mesma saída de dados da API regular, mais as informações relevantes do cabeçalho de HTTP.

$ curl https://api.github.com?callback=foo

> /**/foo({
>   "meta": {
>     "status": 200,
>     "x-ratelimit-limit": "5000",
>     "x-ratelimit-remaining": "4966",
>     "x-ratelimit-reset": "1372700873",
>     "Link": [ // pagination headers and other links
>       ["https://api.github.com?page=2", {"rel": "next"}]
>     ]
>   },
>   "data": {
>     // the data
>   }
> })

Você pode escrever um manipulador do JavaScript para processar o retorno de chamada. Aqui está um exemplo pequeno que você pode experimentar:

<html>
<head>
<script type="text/javascript">
function foo(response) {
  var meta = response.meta;
  var data = response.data;
  console.log(meta);
  console.log(data);
}

var script = document.createElement('script');
script.src = 'https://api.github.com?callback=foo';

document.getElementsByTagName('head')[0].appendChild(script);
</script>
</head>

<body>
  <p>Open up your browser's console.</p>
</body>
</html>

Todos os cabeçalhos têm o mesmo valor da string que os cabeçalhos de HTTP com uma exceção notável: Link. Cabeçalhos de link são pré-analisados para você e chegam como um array de tuplas de [url, options].

Um link que se parece com isto:

Link: <url1>; rel="next", <url2>; rel="foo"; bar="baz"

... será mostrado assim na saída da chamada de retorno:

{
  "Link": [
    [
      "url1",
      {
        "rel": "next"
      }
    ],
    [
      "url2",
      {
        "rel": "foo",
        "bar": "baz"
      }
    ]
  ]
}

Fusos horários

Algumas solicitações que criam novos dados, como a criação de um novo commit, permitem que você forneça informações do fuso horário ao especificar ou marcas de tempo. Aplicamos as seguintes regras, por ordem de prioridade, para determinar as informações do fuso horário para essas chamadas da API.

• Fornecer explicitamente uma marca de tempo ISO 8601 com informações de fuso horário
• Usar o cabeçalho Time-Zone
• Usar o último fuso horário conhecido para o usuário
• Definir como padrão UTC sem outras informações de fuso horário

Observe que essas regras se aplicam somente a dados passados para a API, não a dados retornados pela API. Conforme mencionado no "Esquema", os registros de hora retornados pela API estão em formato UTC, ISO 8601.

Fornecer explicitamente uma marca de tempo ISO 8601 com informações de fuso horário

Para chamadas de API que permitem que uma marca de tempo seja especificada, usamos essa marca de tempo exata. Um exemplo disso é a API para gerenciar commits. Para obter mais informações, confira "Banco de dados do Git".

Esses carimbos de data/hora se parecem com 2014-02-27T15:05:06+01:00. Confira também este exemplo para saber como esses carimbos de data/hora podem ser especificados.

Usar o cabeçalho Time-Zone

É possível fornecer um cabeçalho Time-Zone que define um fuso horário de acordo com a lista de nomes do banco de dados Olson.

curl -H "Time-Zone: Europe/Amsterdam" -X POST https://api.github.com/repos/github-linguist/linguist/contents/new_file.md

Isso significa que geramos uma marca de tempo no momento em que sua chamada de API é feita no fuso horário que este cabeçalho define. Por exemplo, a API para gerenciar conteúdo gera um commit do git para cada adição ou alteração e usa a hora atual como carimbo de data/hora. Para obter mais informações, confira "Repositórios". Este cabeçalho determinará o fuso horário usado para gerar essa marca de tempo atual.

Usar o último fuso horário conhecido para o usuário

Se nenhum cabeçalho Time-Zone for especificado e você fizer uma chamada autenticada para a API, nós usaremos o último fuso horário conhecido para o usuário autenticado. O último fuso horário conhecido é atualizado sempre que você navegar no site de GitHub Enterprise Cloud.

Definir como padrão UTC sem outras informações de fuso horário

Se as etapas acima não resultarem em nenhuma informação, usaremos UTC como o fuso horário para criar o commit do git.