Versión de API
Los recursos disponibles pueden variar entre las versiones de la API de REST. Debes usar el encabezado X-GitHub-Api-Version
para especificar una versión de API. Para obtener más información, vea «Versiones de API».
Schema
Todo el acceso a la API se realiza mediante HTTPS y se accede desde https://api.github.com
. Todos los datos se envían y reciben 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
Los campos en blanco se incluyen como null
en lugar de omitirse.
Todas las marcas de tiempo se devuelven en formato UTC, ISO 8601:
YYYY-MM-DDTHH:MM:SSZ
Para más información sobre las zonas horarias en marcas de tiempo, vea esta sección.
Representaciones de resumen
Al capturar una lista de recursos, la respuesta incluye un subconjunto de los atributos para ese recurso. Es la representación de "resumen" del recurso. (Algunos atributos son caros en términos de cómputo para que la API los proporcione. Por razones de rendimiento, la representación de resumen excluye esos atributos. Para obtener estos atributos, recupera la representación "detallada").
Ejemplo: al obtener una lista de repositorios, obtendrá la representación de resumen de cada repositorio. Aquí, se captura la lista de repositorios propiedad de la organización octokit:
GET /orgs/octokit/repos
Representaciones detalladas
Al capturar un recurso individual, la respuesta incluye habitualmente todos los atributos para ese recurso. Es la representación "detallada" del recurso. (Tenga en cuenta que, en ocasiones, la autorización influye en la cantidad de detalles que se incluyen en la representación).
Ejemplo: al obtener un repositorio individual, obtendrá la representación detallada del repositorio. Aquí, se captura el repositorio octokit/octokit.rb:
GET /repos/octokit/octokit.rb
La documentación proporciona un ejemplo de respuesta para cada método de la API. La respuesta de ejemplo ilustra todos los atributos que se devuelven con ese método.
Authentication
GitHub recomienda que crees un token para autenticarse en la API REST. Para obtener más información sobre el tipo de token que se va a crear, consulta "Autenticación en la API REST".
Para autenticar la solicitud, envía un token en el Authorization
encabezado de la solicitud:
curl --request GET \
--url "https://api.github.com/octocat" \
--header "Authorization: Bearer YOUR-TOKEN" \
--header "X-GitHub-Api-Version: 2022-11-28"
Nota: En la mayoría de los casos, puedes usar Authorization: Bearer
o Authorization: token
para pasar un token. Sin embargo, si vas a pasar un token web JSON (JWT), debes usar Authorization: Bearer
.
Si intentas usar un punto de conexión de la API REST sin un token o con un token que no tenga permisos suficientes, recibirás una respuesta 404 Not Found
o 403 Forbidden
.
Llave/secreto de OAuth2
Aviso de desuso: GitHub interrumpirá la autenticación a la API mediante parámetros de consulta. La autenticación en la API debe realizarse con la Autenticación HTTP básica. El uso de parámetros de consulta para autenticarse en la API ya no funcionará el 5 de mayo de 2021. Para obtener más información, incluidas las interrupciones programadas, vea la entrada de blog.
curl -u my_client_id:my_client_secret 'https://api.github.com/user/repos'
El uso de client_id
y client_secret
no se autentica como usuario, solo identificará tu OAuth App para aumentar el límite de frecuencia. Los permisos se otorgan únicamente a usuarios, no a aplicaciones, y úicamente obtendrás datos que un usuario no autenticado vería. No filtres el secreto de cliente de OAuth App a tus usuarios.
Más información sobre la limitación de frecuencia no autenticada.
Límite de ingresos fallidos
La autenticación con credenciales no válidas devolverá 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"
> }
Después de detectar varias solicitudes con credenciales no válidas en un breve periodo de tiempo, la API rechazará temporalmente todos los intentos de autenticación para el usuario en cuestión (incluidos aquellos con credenciales válidas) con 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
Muchos métodos de la API toman parámetros opcionales. Para las solicitudes GET
, cualquier parámetro que no se haya especificado como un segmento en la ruta se puede pasar como un parámetro de cadena de consulta HTTP:
$ curl -i "https://api.github.com/repos/vmg/redcarpet/issues?state=closed"
En este ejemplo, se proporcionan los valores "vmg" y "redcarpet" para los parámetros :owner
y :repo
de la ruta, mientras se pasa :state
en la cadena de consulta.
En el caso de las solicitudes POST
, PATCH
, PUT
y DELETE
, los parámetros no incluidos en la dirección URL se deben codificar como JSON con un tipo de contenido de "application/json":
$ curl -i --header "Authorization: Bearer YOUR-TOKEN" -d '{"scopes":["repo_deployment"]}' https://api.github.com/authorizations
Punto de conexión raíz
Puede emitir una solicitud GET
al punto de conexión raíz para obtener todas las categorías de punto de conexión compatibles con la API REST:
$ curl
-u USERNAME:TOKEN https://api.github.com
IDs de nodo globales de GraphQL
Consulta la guía sobre "Utilizar las ID de nodo global" para ver información detallada sobre cómo buscar node_id
a través de la API REST y su uso en operaciones de GraphQL.
Errores de cliente
Existen tres posibles tipos de errores de cliente en las llamadas API que reciben cuerpos de solicitud:
-
El envío de código JSON no válido dará como resultado una respuesta
400 Bad Request
.HTTP/2 400 Content-Length: 35 {"message":"Problems parsing JSON"}
-
El envío del tipo incorrecto de valores JSON dará como resultado una respuesta
400 Bad Request
.HTTP/2 400 Content-Length: 40 {"message":"Body should be a JSON object"}
-
El envío de campos no válidos dará como resultado una respuesta
422 Unprocessable Entity
.HTTP/2 422 Content-Length: 149 { "message": "Validation Failed", "errors": [ { "resource": "Issue", "field": "title", "code": "missing_field" } ] }
Todos los objetos de error tienen propiedades de campo y de recurso para que el cliente pueda identificar el problema. También hay un código de error para que sepa cuál es el error en el campo.
Código de error | Descripción |
---|---|
missing | Un recurso no existe. |
missing_field | No se ha configurado un campo requerido en un recurso. |
invalid | El formato de un campo es inválido. Revisa la documentación para encontrar información más específica. |
already_exists | Otro recurso tiene el mismo valor que este campo. Esto puede suceder en recursos que deben tener claves únicas (tales como nombres de etiqueta). |
unprocessable | Las entradas proporcionadas son inválidas. |
Los recursos también pueden enviar errores de validación personalizados (donde code
es custom
). Los errores personalizados siempre tendrán un campo message
que describe el error y la mayoría también incluirán un campo documentation_url
que apunta a algún contenido que pueda ayudarle a resolver el error.
Redireccionamientos HTTP
La API REST de GitHub Enterprise Cloud usa el redireccionamiento HTTP cuando corresponda. Los clientes deben asumir que cualquier solicitud podría resultar en un redireccionamiento. La recepción de un redireccionamiento HTTP no es un error y los clientes deben seguir esa redirección. Las respuestas de redireccionamiento tienen un campo de encabezado Location
que contiene el URI del recurso al que el cliente debe repetir las solicitudes.
Un código de estado 301
indica un redireccionamiento permanente. El URI que ha usado para realizar la solicitud se ha reemplazado por el especificado en el campo de encabezado Location
. Ésta y todas las solicitudes futuras a este recurso se deberán dirigir al nuevo URI.
Un código de estado 302
o 307
indica un redireccionamiento temporal. La solicitud debe repetirse literalmente en el URI especificado en el campo de encabezado Location
, pero los clientes deben seguir utilizando el URI original para solicitudes futuras.
Podrían utilizarse otros códigos de estado de redirección de acuerdo con la especificación HTTP 1.1.
Verbos HTTP
Siempre que sea posible, la API REST de GitHub Enterprise Cloud se esfuerza por usar los verbos HTTP adecuados para cada acción. Ten en cuenta que los verbos HTTP distinguen mayúsculas de minúsculas.
Verbo | Descripción |
---|---|
HEAD | Puede emitirse contra cualquier recurso para obtener solo la información del encabezado HTTP. |
GET | Se utiliza para recuperar recursos. |
POST | Se utiliza para crear recursos. |
PATCH | Se utiliza para actualizar los recursos con datos parciales de JSON. Por ejemplo, un recurso Incidencia tiene atributos title y body . Una solicitud PATCH podría aceptar uno o más de los atributos para actualizar el recurso. |
PUT | Se utiliza para reemplazar recursos o colecciones. Para las solicitudes PUT sin un atributo body , asegúrese de establecer el encabezado Content-Length en cero. |
DELETE | Se utiliza para borrar recursos. |
Hypermedia
Todos los recursos pueden tener una o varias propiedades *_url
vinculadas a otros recursos. Su función es proporcionar las URL explícitas para que los clientes de API adecuados no tengan que construirlas ellos mismos. Se recomienda encarecidamente que los clientes de API las usen. De esta forma, para los desarrolladores será más sencillo realizar actualizaciones futuras de la API. Se espera que todas las direcciones URL sean plantillas de URI RFC 6570 correctas.
Después, puede expandir estas plantillas con algo parecido a la gema 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"
Paginación
Si una respuesta de la API de REST fuera a incluir muchos resultados, GitHub paginaría los resultados y devolvería un subconjunto de los resultados. Puedes usar el encabezado de vínculo de la respuesta para solicitar páginas de datos adicionales. Si un punto de conexión admite el parámetro de consulta per_page
, puedes controlar cuántos resultados se devuelven en una página. Para más información sobre la paginación, consulta "Uso de la paginación en la API de REST".
Tiempos de espera
Si GitHub tarda más de 10 segundos en procesar una solicitud de la API, GitHub finalizará la solicitud y recibirás una respuesta de tiempo de espera excedido como la siguiente:
{
"message": "Server Error"
}
GitHub Enterprise Cloud se reserva el derecho de cambiar la ventana de tiempo de espera para proteger la velocidad y confiabilidad de la API.
Limitación de frecuencia
La API REST GitHub Enterprise Cloud usa la limitación de frecuencia para controlar el tráfico de la API. Cada tipo de solicitud de API tiene distintos límites de frecuencia. Los encabezados de respuesta describen el estado actual del límite de frecuencia.
Límites de frecuencia
Los distintos tipos de solicitudes de la API a GitHub.com están sujetas a límites de tasa diferentes. Además, los puntos de conexión de búsqueda tienen límites dedicados. Para más información, consulta "Search" en la documentación de REST API.
Límites de frecuencia para solicitudes de cuentas personales
Puedes hacer solicitudes directas de la API que autentiques con un personal access token. Los OAuth App o GitHub App también pueden realizar una solicitud en tu nombre después de autorizar la aplicación. Para más información, consulte "Creación de un token de acceso personal," "Autorización de aplicaciones de OAuth" y "Autorizar GitHub Apps".
GitHub Enterprise Cloud asocia todas estas solicitudes con el usuario autenticado. Para OAuth Apps y GitHub Apps, este es el usuario que autorizó la aplicación. Todas estas solicitudes cuentan en el límite de tasa del usuario autenticado.
Usuario a servidor se limitan a 5000 por hora y por usuario autenticado. Todas las solicitudes de las aplicaciones de OAuth autorizadas por un usuario o un personal access token propiedad del usuario, y las solicitudes autenticadas con cualquiera de las credenciales de autenticación del usuario, comparten la misma cuota de 5000 solicitudes por hora para ese usuario.
Las solicitudes de token de acceso de usuario están sujetas a un límite alto de 15.000 solicitudes por hora y por usuario autenticado en los siguientes escenarios:
- La solicitud es desde una GitHub App que pertenece a una organización de GitHub Enterprise Cloud.
- La solicitud es desde una OAuth App que pertenece a o está aprobada por una organización de GitHub Enterprise Cloud.
Para las solicitudes no autenticadas, el límite de tasa permite hasta 60 solicitudes por hora. Las solicitudes sin autenticar se asocian con la dirección IP original y no con la persona que las realiza.
Límites de frecuencia para solicitudes de GitHub Apps
Las solicitudes de GitHub App pueden usar un token de acceso de usuario o un token de acceso de instalación. Para más información sobre los límites de frecuencia para GitHub Apps, consulta "Límites de frecuencia para aplicaciones de GitHub".
Límites de frecuencia para solicitudes de GitHub Actions
Puede usar el valor GITHUB_TOKEN
integrado para autenticar solicitudes en flujos de trabajo de Acciones de GitHub. Para obtener más información, vea «Autenticación automática de tokens».
Al usar GITHUB_TOKEN
, el límite de frecuencia es de 1000 solicitudes por hora y repositorio. Para las solicitudes a recursos que pertenecen a una cuenta de empresa de GitHub.com, se aplica el límite de frecuencia de GitHub Enterprise Cloud y es de 15 000 solicitudes por hora y repositorio.
Verificar el estado de tu límite de tasa
Los encabezados de respuesta describen el estado actual del límite de frecuencia. También puedes usar la API REST para encontrar el número actual de llamadas API disponibles para ti o la aplicación en un momento dado.
Encabezados de límite de frecuencia
Los encabezados de respuesta x-ratelimit
describen el estado actual del límite de frecuencia después de cada solicitud:
$ 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
Nombre de encabezado | Descripción |
---|---|
x-ratelimit-limit | La cantidad máxima de solicitudes que puedes hacer por hora. |
x-ratelimit-remaining | La cantidad de solicitudes que quedan en la ventana de límite de tasa actual. |
x-ratelimit-used | La cantidad de solicitudes que has realizado en la ventana de límite de tasa actual. |
x-ratelimit-reset | Hora a la que se restablece la ventana de límite de frecuencia actual en segundos desde la época UTC. |
Comprobación del estado del límite de frecuencia con la API REST
Puedes usar la API REST para comprobar el estado del límite de frecuencia sin incurrir en el uso de ese límite. Para obtener más información, vea «Límite de frecuencia». Siempre que sea posible, GitHub recomienda usar los encabezados de respuesta x-ratelimit
en su lugar para reducir la carga en la API.
Superación del límite de frecuencia
Si superas el límite de frecuencia, la respuesta tendrá un estado 403
y el encabezado 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"
> }
Si la frecuencia está limitada, no debes intentar la solicitud hasta después del valor especificado por el tiempo x-ratelimit-reset
.
Aumentar el límite de frecuencia no autenticada para OAuth Apps
Si tu OAuth App necesita hacer llamadas sin autenticar a recursos públicos con un límite de tasa más alto, puedes pasar el identificador y el secreto de cliente de la aplicación antes de la ruta de la terminal.
$ 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
Nota: Nunca comparta el secreto de cliente con nadie ni lo incluya en el código del explorador del lado cliente.
Quedarse dentro del límite de tasa
Si supera el límite de frecuencia mediante la autenticación básica u OAuth, es probable que pueda corregir el problema almacenando en caché las respuestas de la API y usando solicitudes condicionales.
Límites de tasa secundarios
Los límites de frecuencia descritos anteriormente se aplican a toda la API REST y son para cada usuario o aplicación. Para prorpocionar un servicio de calidad en GitHub Enterprise Cloud, los límites de tasa adicionales podrían aplicar a algunas acciones cuando se utiliza la API. Por ejemplo, utilizar la API para crear contenido rápidamente, sondear de manera agresiva en vez de usar webhooks, realizar solicitudes múltiples concurrentes, o bien solicitar repetidamente datos que son costosos a nivel computacional, podría dar como resultado una limitación de frecuencia adicional.
Estos límites de frecuencia adicionales no deben interferir con el uso legítimo de la API. Tus límites de tasa habituales deben ser el único límite en el cual te enfoques. Para asegurarse de que actúa como un buen ciudadano de API, consulte nuestras Instrucciones de procedimientos recomendados.
Si la aplicación activa desencadena un límite de frecuencia adicional, recibirás una respuesta 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"
> }
Debes esperar e intentar la solicitud de nuevo después de unos minutos. Si el encabezado de respuesta retry-after
está presente, no debes reintentar la solicitud hasta que hayan transcurrido los segundos indicados. En caso contrario, no debes reintentar la solicitud hasta la hora, en segundos de época UTC, especificada por el encabezado x-ratelimit-reset
.
Se requiere un agente de usuario
Todas las solicitudes de API DEBEN incluir un encabezado User-Agent
válido. Las solicitudes sin un encabezado User-Agent
se rechazarán. Le pedimos que use el nombre de usuario de GitHub Enterprise Cloud, o el nombre de la aplicación, para el valor del encabezado User-Agent
. Esto nos permite contactarte en caso de que haya algún problema.
Este es un ejemplo:
User-Agent: Awesome-Octocat-App
curl envía un encabezado User-Agent
válido de forma predeterminada. Si proporciona un encabezado User-Agent
no válido mediante curl (o un cliente alternativo), recibirá una respuesta 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.
Solicitudes condicionales
La mayoría de las respuestas devuelven un encabezado ETag
. Muchas respuestas también devuelven un encabezado Last-Modified
. Puede usar los valores de estos encabezados para realizar solicitudes posteriores a esos recursos con los encabezados If-None-Match
y If-Modified-Since
, respectivamente. Si el recurso no ha cambiado, el servidor devolverá 304 Not Modified
.
Nota: Realizar una solicitud condicional y recibir una respuesta 304 no cuenta para el límite de frecuencia, por lo que le recomendamos que lo use siempre que sea posible.
$ 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
Uso compartido de recursos entre orígenes
La API es compatible con el Intercambio de recursos de origen Cruzado (CORS, por sus siglas en inglés) para las solicitudes de AJAX desde cualquier origen. Puede leer la recomendación de CORS del W3C o esta introducción de la Guía de seguridad de HTML 5.
Esta es una solicitud de ejemplo enviada desde un explorador destinada a 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
Así se ve una solicitud de prevuelo de CORS:
$ 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
Rellamados de JSON-P
Puede enviar un parámetro ?callback
a cualquier llamada GET para que los resultados se encapsulen en una función JSON. Esto se suele usar cuando los exploradores quieren insertar contenido de GitHub Enterprise Cloud en páginas web evitando los problemas de dominios cruzados. La respuesta incluye la misma salida de datos que la API común, además de la información pertinente del encabezado 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
> }
> })
Puedes escribir un agente de JavaScript para procesar la rellamada. Aquí hay un ejemplo minimalista que puedes probar:
<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 los encabezados son el mismo valor de cadena que los encabezados HTTP con una excepción concreta: Link. Los encabezados Link se analizan previamente de forma automática y se pasan como una matriz de tuplas [url, options]
.
Un enlace que se ve así:
Link: <url1>; rel="next", <url2>; rel="foo"; bar="baz"
... se verá así en la salida de la rellamada:
{
"Link": [
[
"url1",
{
"rel": "next"
}
],
[
"url2",
{
"rel": "foo",
"bar": "baz"
}
]
]
}
Zonas horarias
Algunas solicitudes que crean datos nuevos, tales como aquellas para crear una confirmación nueva, te permiten proporcionar información sobre la zona horaria cuando especificas o generas marcas de tiempo. Aplicamos las siguientes reglas, en orden de prioridad, para determinar la información de la zona horaria para los llamados a la API.
- Proporcionar explícitamente una marca de tiempo ISO 8601 con la información de zona horaria
- Uso del encabezado
Time-Zone
- Uso de la última zona horaria conocida para el usuario
- Uso predeterminado de UTC cuando no existe información sobre otra zona horaria
Toma en cuenta que estas reglas se aplican únicamente a los datos que se pasan a la API y no a los que esta devuelve. Como se ha mencionado en "Esquema", las marcas de tiempo devueltas por la API están en hora UTC, en formato ISO 8601.
Proporcionar explícitamente una marca de tiempo de tipo ISO 8601 con la información de la zona horaria
Para las llamadas a la API que permitan que se especifique una marca de tiempo, utilizamos esa marca de tiempo exacta. Un ejemplo de esto es la API para administrar confirmaciones. Para obtener más información, vea «Base de datos de Git».
Estas marcas de tiempo son similares a 2014-02-27T15:05:06+01:00
. Vea también este ejemplo para saber cómo se pueden especificar estas marcas de tiempo.
Uso del encabezado Time-Zone
Es posible proporcionar un encabezado Time-Zone
que defina una zona horaria según la lista de nombres de la base de datos Olson.
$ curl -H "Time-Zone: Europe/Amsterdam" -X POST https://api.github.com/repos/github-linguist/linguist/contents/new_file.md
Esto significa que generamos una marca de tiempo para el momento en el se haga el llamado a tu API en la zona horaria que defina este encabezado. Por ejemplo, la API de administración de contenido genera una confirmación de Git para cada adición o cambio, y usa la hora actual como marca de tiempo. Para obtener más información, vea «Repositorios». Este encabezado determinará la zona horaria que se utiliza para generar la marca de tiempo actual.
Utilizar la última zona horaria conocida para el usuario
Si no se especifica ningún encabezado Time-Zone
y realiza una llamada autenticada a la API, se usa la última zona horaria conocida para el usuario autenticado. La última zona horaria conocida se actualiza cuando sea que busques el sitio web de GitHub Enterprise Cloud.
Predeterminarse en UTC cuando no existe otra información sobre la zona horaria
Si los pasos anteriores no dan como resultado ninguna información, utilizaremos UTC como la zona horaria para crear la confirmación de git.