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"
Observação: Na maioria dos casos, você pode usar Authorization: Bearer
ou Authorization: token
a fim de passar um token. No entanto, se estiver passando um JWT (token Web JSON), você deverá usar Authorization: Bearer
.
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
Aviso de reprovação: o GitHub descontinuará a autenticação na API com parâmetros de consulta. A autenticação na API deve ser feita com a autenticação básica HTTP. O uso de parâmetros de consulta para autenticação na API deixou de funcionar em 5 de maio de 2021. Para obter mais informações, incluindo brownouts agendados, confira a postagem no blog.
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.
Leia mais sobre limite de taxa não autenticada.
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_id
s por meio da API REST e usá-los em operações do GraphQL.
Erros do cliente
Há três tipos possíveis de erros de cliente em chamadas de API que recebem corpos de solicitação:
-
O envio de JSON inválido resultará em uma resposta
400 Bad Request
.HTTP/2 400 Content-Length: 35 {"message":"Problems parsing JSON"}
-
O envio do tipo errado de valores JSON resultará em uma resposta
400 Bad Request
.HTTP/2 400 Content-Length: 40 {"message":"Body should be a JSON object"}
-
O envio de campos inválidos resultará em uma resposta
422 Unprocessable Entity
.HTTP/2 422 Content-Length: 149 { "message": "Validation Failed", "errors": [ { "resource": "Issue", "field": "title", "code": "missing_field" } ] }
Todos os objetos de erro têm propriedades de recursos e campos para que seu cliente possa dizer qual é o problema. Há também um código de erro para que você saiba o que está errado com o campo.
Código do erro | Descrição |
---|---|
missing | Um recurso não existe. |
missing_field | Não foi definido um campo obrigatório em um recurso. |
invalid | Formatação de um campo é inválida. Revise a documentação para obter informações mais específicas. |
already_exists | Outro recurso tem o mesmo valor que este campo. Isso pode acontecer em recursos que precisam ter alguma chave única (como nomes de etiqueta). |
unprocessable | As entradas fornecidas eram inválidas. |
Os recursos também podem enviar erros de validação personalizados (em que code
e custom
). Os erros personalizados sempre terão um campo de message
que descreve o erro e a maioria dos erros também incluirá um campo de documentation_url
que aponta para algum conteúdo que pode ajudá-lo a resolver o erro.
Redirecionamentos HTTP
A API REST do GitHub Enterprise Cloud usa o redirecionamento HTTP quando apropriado. Os clientes devem assumir que qualquer solicitação pode resultar em um redirecionamento. Receber um redirecionamento de HTTP não é um erro e os clientes devem seguir esse redirecionamento. As respostas de redirecionamento terão
um campo do cabeçalho do tipo Location
que contém o URI do recurso ao qual o cliente deve repetir as solicitações.
Um código de status 301
indica redirecionamento permanente. O URI que você usou para fazer a solicitação foi substituído pelo especificado no campo do cabeçalho Location
. Este e todas as solicitações futuras deste recurso devem ser direcionadas para o novo URI.
Um código de status302
ou 307
indica o redirecionamento temporário. A solicitação deve ser repetida literalmente para o URI especificado no campo de cabeçalho Location
, mas os clientes devem continuar a usar o URI original para solicitações futuras.
Outros códigos de status de redirecionamento podem ser usados de acordo com a especificação HTTP 1.1.
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"
Paginação
Quando uma resposta da API REST incluir muitos resultados, GitHub paginará os resultados e retornará um subconjunto dos resultados. Você pode usar o cabeçalho do link da resposta para solicitar páginas adicionais de dados. Se um ponto de extremidade oferecer suporte ao parâmetro de consulta per_page
, você poderá controlar quantos resultados são retornados em uma página. Para saber mais sobre paginação, confira "Como usar paginação na API REST".
Tempos limite
Se GitHub leva mais de 10 segundos para processar uma solicitação de API, GitHub encerrará a solicitação e você receberá uma resposta de tempo limite como esta:
{
"message": "Server Error"
}
GitHub Enterprise Cloud se reserva o direito de alterar o período de tempo limite para proteger a velocidade e confiabilidade da API.
Limitação de taxa
A API REST do GitHub Enterprise Cloud usa limitação de taxa para controlar o tráfego da API. Diferentes tipos de solicitações de API têm limites de taxa distintos. Os cabeçalhos de resposta descrevem o status do limite da taxa atual.
Limites de taxa
Os diferentes tipos de solicitações da API para GitHub.com estão sujeitos a diferentes limites de taxa. Além disso, os pontos de extremidade de Pesquisa têm limites dedicados. Para obter mais informações, confira "Search" na documentação da API REST.
Limites de taxa para solicitações de contas pessoais
Você pode fazer solicitações diretas de API autenticadas com um personal access token. Um OAuth App ou GitHub App também poderá fazer uma solicitação em seu nome depois que você autorizar o aplicativo. Para saber mais, confira "Managing your personal access tokens", "Autorizando Aplicativos OAuth" e "Autorizando aplicativos GitHub".
O GitHub Enterprise Cloud associa todas essas solicitações ao usuário autenticado. Para OAuth Apps e GitHub Apps, esse é o usuário que autorizou o aplicativo. Todos essas solicitações contam para o limite de taxa do usuário autenticado.
Token de acesso do usuário são limitadas a 5.000 solicitações por hora e por usuário autenticado. Todas as solicitações de aplicativos OAuth autorizadas por um usuário ou um personal access token pertencente ao usuário e as solicitações autenticadas com uma das credenciais de autenticação do usuário compartilham a cota de cinco mil solicitações por hora para esse usuário.
As solicitações do token de acesso do usuário estão sujeitas a um limite superior de 15 mil solicitações por hora e por usuário autenticado nos seguintes cenários:
- A solicitação é de um GitHub App que pertence a uma organização do GitHub Enterprise Cloud.
- A solicitação é de um OAuth App que pertence a uma organização do GitHub Enterprise Cloud ou que é aprovado por ela.
Para solicitações não autenticadas, o limite de taxa permite até 60 solicitações por hora. As solicitações não autenticadas estão associadas ao endereço IP original, e não à pessoa que faz as solicitações.
Limites de taxa para solicitações de GitHub Apps
As solicitações de um GitHub App podem usar um token de acesso do usuário ou um token de acesso de instalação. Para obter mais informações sobre limites de taxa para GitHub Apps, confira "Limites de taxa para aplicativos GitHub".
Limites de taxa para solicitações de GitHub Actions
Você pode utilizar o GITHUB_TOKEN
integrado para autenticar as solicitações nos fluxos de trabalho do GitHub Actions. Para obter mais informações, confira "Autenticação automática de token".
Quando GITHUB_TOKEN
é usado, o limite de taxa é de 1.000 solicitações por hora por repositório. Para solicitações a recursos que pertencem a uma conta corporativa na GitHub.com, aplicam-se os limites de taxa do GitHub Enterprise Cloud e o limite é de 15.000 solicitações por hora por repositório.
Verificando o status do seu limite da taxa
Os cabeçalhos de resposta descrevem o status do limite da taxa atual. Você também pode usar a API REST para localizar o número atual de chamadas à API disponíveis para você ou seu aplicativo a qualquer momento.
Cabeçalhos de limite de taxa
Os cabeçalhos de resposta x-ratelimit
descrevem o status do limite de taxa atual após cada solicitação:
$ curl -i https://api.github.com/users/octocat
> HTTP/2 200
> x-ratelimit-limit: 60
> x-ratelimit-remaining: 56
> x-ratelimit-used: 4
> x-ratelimit-reset: 1372700873
Nome do cabeçalho | Descrição |
---|---|
x-ratelimit-limit | O número máximo de solicitações que você pode fazer por hora. |
x-ratelimit-remaining | O número de solicitações restantes na janela de limite de taxa atual. |
x-ratelimit-used | O número de solicitações feitas na janela de limite de taxa atual. |
x-ratelimit-reset | O tempo em que a janela de limite de taxa atual é redefinida em segundos de época UTC. |
Como verificar o status do limite de taxa com a API REST
Você pode usar a API REST para verificar o status do seu limite de taxa sem impactar no limite atual. Para obter mais informações, confira "Limite de taxa". Sempre que possível, GitHub recomenda usar os cabeçalhos de resposta x-ratelimit
para diminuir a carga na API.
Excedendo o limite de taxa
Se você exceder o limite de taxa, a resposta terá um status 403
e o cabeçalho x-ratelimit-remaining
será 0
:
> HTTP/2 403
> Date: Tue, 20 Aug 2013 14:50:41 GMT
> x-ratelimit-limit: 60
> x-ratelimit-remaining: 0
> x-ratelimit-used: 60
> 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/rest/overview/resources-in-the-rest-api#rate-limiting"
> }
Se você tiver uma taxa limitada, não deverá tentar sua solicitação até depois do tempo especificado pelo tempo x-ratelimit-reset
.
Aumentar o limite de taxa não autenticado em OAuth Apps
Se o seu OAuth App precisar fazer chamadas não autenticadas a um recurso público em um limite de taxa mais alto, você poderá passar a ID e o segredo do cliente do seu aplicativo antes do roteamento dos pontos de extremidade.
$ curl -u my_client_id:my_client_secret -I https://api.github.com/meta
> HTTP/2 200
> Date: Mon, 01 Jul 2013 17:27:06 GMT
> x-ratelimit-limit: 5000
> x-ratelimit-remaining: 4966
> x-ratelimit-used: 34
> x-ratelimit-reset: 1372700873
Observação: Nunca compartilhe seu segredo de cliente com alguém ou o inclua no código do navegador do lado do cliente.
Manter-se dentro do limite de taxa
Se você exceder o limite de taxa usando a autenticação básica ou o OAuth, provavelmente poderá corrigir o problema armazenando em cache as respostas da API e usando solicitações condicionais.
Limites de taxa secundária
Os limites de taxa descritos acima se aplicam a toda a API REST e são contabilizados por usuário ou por aplicativo. A fim de fornecer serviço de qualidade no GitHub Enterprise Cloud, podem-se aplicar limites de taxa adicionais podem a algumas ações ao usar a API. Por exemplo, usar a API para criar rapidamente conteúdo, fazer sondagem de modo agressivo em vez de usar webhooks, fazer várias solicitações simultâneas ou solicitar repetidamente dados caros do ponto de vista computacional podem resultar na limitação da taxa adicional.
Esses limites de taxa adicionais não pretendem interferir com o uso legítimo da API. Seus limites de taxa normais devem ser o único limite em que você deve focar. Para garantir que você esteja agindo como um bom cidadão da API, confira nossas Diretrizes de Práticas Recomendadas.
Se o seu aplicativo disparar um limite de taxa adicional, você receberá uma resposta informativa:
> 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/rest/overview/resources-in-the-rest-api#secondary-rate-limits"
> }
Você deve aguardar e tentar sua solicitação novamente após alguns minutos. Se o cabeçalho de resposta retry-after
estiver presente, você não deverá repetir sua solicitação até que esse número de segundos tenha decorrido. Caso contrário, você não deverá repetir sua solicitação até que chegue a hora, em segundos de UTC, especificada pelo cabeçalho x-ratelimit-reset
.
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.
Solicitações condicionais
A maioria das respostas retorna um cabeçalho ETag
. Muitas respostas também retornam um cabeçalho Last-Modified
. Você pode usar os valores desses cabeçalhos para fazer solicitações subsequentes a esses recursos usando os cabeçalhos If-None-Match
e If-Modified-Since
, respectivamente. Se o recurso não tiver sido alterado, o servidor retornará um 304 Not Modified
.
Observação: Fazer uma solicitação condicional e receber uma resposta 304 não conta para o seu Limite de Taxa. Portanto, recomendamos que você o utilize sempre que possível.
$ curl -I https://api.github.com/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 https://api.github.com/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 https://api.github.com/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 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.