Recursos na API REST

Isso descreve os recursos que formam a API REST oficial de GitHub Enterprise Server. Em caso de problema ou solicitação, entre em contato com your site administrator.

Versão atual

Por padrão, todas as solicitações para http(s)://[hostname]/api/v3 recebem a versão v3 da API REST. Nós incentivamos que você a solicite explicitamente esta versão por meio do cabeçalho Aceitar.

Accept: application/vnd.github.v3+json

Esquema

a API é acessada a partir de http(s)://[hostname]/api/v3. Todos os dados são enviados e recebidos como JSON.

$ curl -I http(s)://[hostname]/api/v3/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
> X-GitHub-Enterprise-Version: 3.1.0
> 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 nos registros de tempo, consulte 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 a �  organização do 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. (Note que a autorização por vezes influencia o valor de detalhes incluído na representação.)

Exemplo: ao receber um repositório individual, você recebe a representação detalhada do repositório. Aqui, nós 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. O exemplo da resposta ilustra todos os atributos retornados por esse método.

Autenticação

Existem duas maneiras de efetuar a autenticação por meio da API REST de GitHub Enterprise Server. As solicitações que exigem autenticação retornarão 404 Not Found, em vez de 403 Forbidden em alguns lugares. Isso é para evitar a fuga acidental de repositórios privados para usuários não autorizados.

Autenticação básica

$ curl -u "username" http(s)://[hostname]/api/v3

Token do OAuth2 (enviado em um cabeçalho)

$ curl -H "Authorization: token OAUTH-TOKEN" http(s)://[hostname]/api/v3

Leia mais sobre o OAuth2. Observe que os tokens do OAuth2 podem ser adquiridos usando o fluxo de aplicação web para aplicativos de produção.

OAuth2 key/secret

curl -u my_client_id:my_client_secret 'http(s)://[hostname]/api/v3/user/repos'

Usar o seu client_id e client_secret não autenticam você como usuário. Isso apenas irá identificar o seu aplicativo OAuth para aumentar o seu 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. Por este motivo, você só deve usar a chave/segredo OAuth2 em cenários de servidor para servidor. Não deixe vazar o segredo do cliente do OAuth do seu aplicativo para os seus usuários.

Você não conseguirá efetuar a autenticação usando sua chave e segredo do OAuth2 enquanto estiver no modo privado e essa tentativa de autenticação irá retornar 401 Unauthorized. Para obter mais informações, consulte "Habilitar o modo privado".

Falha no limite de login

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

$ curl -I http(s)://[hostname]/api/v3 -u foo:bar
> HTTP/2 401

> {
>   "message": "Bad credentials",
>   "documentation_url": "https://docs.github.com/enterprise/3.1/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:

$ curl -i http(s)://[hostname]/api/v3 -u -u valid_username:valid_password 
> HTTP/2 403
> {
>   "message": "Maximum number of login attempts exceeded. Please try again later.",
>   "documentation_url": "https://docs.github.com/enterprise/3.1/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 "http(s)://[hostname]/api/v3/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 string da consulta.

Para solicitações de POST, PATCH, PUTe EXCLUIR, os parâmetros não incluídos na URL devem ser codificados como JSON com um Content-Type de 'application/json':

$ curl -i -u username -d '{"scopes":["repo_deployment"]}' http(s)://[hostname]/api/v3/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:password http(s)://[hostname]/api/v3

IDs de nós globais do GraphQL

Consulte o guia em "Usar IDs do nó globais " para obter informações detalhadas sobre como encontrar node_ids através da API REST e usá-los em operações do GraphQL.

Erros do cliente

Há três tipos possíveis de erros de cliente na chamadas da API que recebem textos:

1. O envio de um JSON inválido resultará em uma resposta 400 Bad Request`.

 HTTP/2 400
 Content-Length: 35

 {"message":"Problems parsing JSON"}
`

   HTTP/2 400
   Content-Length: 40
  
   {"message":"Body should be a JSON object"}

   HTTP/2 422
   Content-Length: 149
  
   {
     "message": "Validation Failed",
     "errors": [
       {
         "resource": "Issue",
         "field": "title",
         "code": "missing_field"
       }
     ]
   }
  </ol>

>> 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"

$ curl 'http(s)://[hostname]/api/v3/user/repos?page=2&per_page=100'

Link: <http(s)://[hostname]/api/v3/user/repos?page=3&per_page=100>; rel="next",
  <http(s)://[hostname]/api/v3/user/repos?page=50&per_page=100>; rel="last"

Link: <http(s)://[hostname]/api/v3/orgs/ORG/audit-log?after=MTYwMTkxOTU5NjQxM3xZbGI4VE5EZ1dvZTlla09uWjhoZFpR&before=>; rel="next",

$ curl -I http(s)://[hostname]/api/v3/users/octocat
> HTTP/2 200
> Date: Mon, 01 Jul 2013 17:27:06 GMT
> x-ratelimit-limit: 60
> x-ratelimit-remaining: 56
> x-ratelimit-reset: 1372700873

new Date(1372700873 * 1000)
// => Mon Jul 01 2013 13:47:53 GMT-0400 (EDT)

> HTTP/2 403
> Date: Tue, 20 Aug 2013 14:50:41 GMT
> x-ratelimit-limit: 60
> x-ratelimit-remaining: 0
> x-ratelimit-reset: 1377013266

> {
>    "message": "API rate limit exceeded for xxx.xxx.xxx.xxx. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)",
>    "documentation_url": "https://docs.github.com/enterprise/3.1/rest/overview/resources-in-the-rest-api#rate-limiting"
> }

$ curl -u my_client_id:my_client_secret -I http(s)://[hostname]/api/v3/user/repos
> HTTP/2 200
> Date: Mon, 01 Jul 2013 17:27:06 GMT
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4966
> x-ratelimit-reset: 1372700873

> HTTP/2 403
> Content-Type: application/json; charset=utf-8
> Connection: close

> {
>   "message": "You have exceeded a secondary rate limit and have been temporarily blocked from content creation. Please retry your request again later.",
>   "documentation_url": "https://docs.github.com/enterprise/3.1/rest/overview/resources-in-the-rest-api#secondary-rate-limits"
> }

A maioria das respostas retorna um cabeçalho de Etag. Muitas respostas também retornam um cabeçalho <code>Last-Modified. Você pode usar os valores desses cabeçalhos para fazer solicitações subsequentes para esses recursos usando os cabeçalhos If-None-Match e If-Modified-Desde, respectivamente. Se o recurso não foi alterado, o servidor retornará 304 não modificado.

$ curl -I http(s)://[hostname]/api/v3/user
> HTTP/2 200
> Cache-Control: private, max-age=60
> ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Vary: Accept, Authorization, Cookie
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4996
> x-ratelimit-reset: 1372700873

$ curl -I http(s)://[hostname]/api/v3/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
> HTTP/2 304
> Cache-Control: private, max-age=60
> ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Vary: Accept, Authorization, Cookie
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4996
> x-ratelimit-reset: 1372700873

$ curl -I http(s)://[hostname]/api/v3/user -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT"
> HTTP/2 304
> Cache-Control: private, max-age=60
> Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
> Vary: Accept, Authorization, Cookie
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4996
> x-ratelimit-reset: 1372700873

Compartilhamento de recursos de origem cruzada

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 do CORS W3C ou esta introdução do Guia de Segurança do HTML 5.

Aqui está uma solicitação de exemplo enviada a partir de uma consulta em http://exemplo.com:

$ curl -I http(s)://[hostname]/api/v3 -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 http(s)://[hostname]/api/v3 -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 é normalmente usado quando os navegadores querem que incorporem GitHub Enterprise Server conteúdo em páginas da web, contornando problemas de de domínio cruzado. A resposta inclui a mesma saída de dados da API regular, mais as informações relevantes do cabeçalho de HTTP.

$ curl http(s)://[hostname]/api/v3?callback=foo

> /**/foo({
>   "meta": {
>     "status": 200,
>     "x-ratelimit-limit": "5000",
>     "x-ratelimit-remaining": "4966",
>     "x-ratelimit-reset": "1372700873",
>     "Link": [ // pagination headers and other links
>       ["http(s)://[hostname]/api/v3?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 = 'http(s)://[hostname]/api/v3?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 d a 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 de Commits.

Essas marcas de tempo se parecem com 2014-02-27T15:05:06+01:00. Veja também este exemplo para saber como essas marcas de tempo podem ser especificadas.

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 http(s)://[hostname]/api/v3/repos/github/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, o API de Conteúdo gera um commit do git para cada adição ou alteração e usa a hora atual como marca de tempo. 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 Server.

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.