Recursos en la API de REST

Schema

A la API se accede desde https://HOSTNAME/api/v3. Todos los datos se envían y reciben como JSON.

$ curl -I https://<em>HOSTNAME</em>/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: GitHub AE
> 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://HOSTNAME/api/v3/octocat" \
--header "Authorization: Bearer YOUR-TOKEN"

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.

La autenticación con credenciales no válidas devolverá 401 Unauthorized:

$ curl -I https://<em>HOSTNAME</em>/api/v3 --header "Authorization: Bearer INVALID-TOKEN"
> HTTP/2 401

> {
>   "message": "Bad credentials",
>   "documentation_url": "https://docs.github.com/github-ae@latest/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/github-ae@latest/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://<em>HOSTNAME</em>/api/v3/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, PUTy 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://<em>HOSTNAME</em>/api/v3/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://<em>HOSTNAME</em>/api/v3

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.

Verbos HTTP

Siempre que sea posible, la API REST de GitHub AE 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"

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://<em>HOSTNAME</em>/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

Así se ve una solicitud de prevuelo de CORS:

$ curl -I https://<em>HOSTNAME</em>/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

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 AE 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://<em>HOSTNAME</em>/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
>       ["https://<em>HOSTNAME</em>/api/v3?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://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 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://<em>HOSTNAME</em>/api/v3/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 AE.

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.

Recursos en la API de REST

En este artículo