Introducción a la API REST

Introducción

En este artículo se describe cómo usar la API REST de GitHub con GitHub CLI, curl o JavaScript. Para obtener una guía de inicio rápido, consulta Inicio rápido para GitHub API REST.

Acerca de las solicitudes a la API de REST

En esta sección se describen los elementos que componen una solicitud de API:

•         [HTTP method](#http-method) (Método HTTP)
  

•         [Path](#path)
  

•         [Encabezados](#headers)
  

•         [Tipos de medios](#media-types)
  

•         [Autenticación](#authentication)
  

•         [Parámetros](#parameters)
  

Cada solicitud a la API de REST incluye un método HTTP y una ruta de acceso. Según el punto de conexión de API de REST, es posible que también tengas que especificar encabezados de solicitud, información de autenticación, parámetros de consulta o parámetros de cuerpo.

La documentación de referencia de la API de REST describe el método HTTP, la ruta de acceso y los parámetros de cada operación. También muestra solicitudes y respuestas de ejemplo para cada punto final. Para más información, consulta la Documentación de referencia de REST.

Método HTTP

El método HTTP de un punto de conexión define el tipo de acción que realiza en un recurso determinado. Algunos métodos HTTP comunes son GET, POST, DELETE y PATCH. La documentación de referencia de la API de REST proporciona el método HTTP de cada punto de conexión.

Por ejemplo, el método HTTP para el punto de conexión "Enumerar problemas del repositorio" es GET.

Siempre que sea posible, la API REST de GitHub intenta por todos los medios usar el método HTTP adecuado para cada acción.

•         `GET`: se utiliza para recuperar recursos.
  

•         `POST`: se utiliza para crear recursos.
  

•         `PATCH`: se utiliza para actualizar propiedades de los recursos.
  

•         `PUT`: se utiliza para reemplazar recursos o colecciones de recursos.
  

•         `DELETE`: se utiliza para borrar recursos.
  

Ruta

Cada punto de conexión tiene una ruta de acceso. La documentación de referencia de API de REST proporciona la ruta de acceso de cada punto de conexión. Por ejemplo, la ruta de acceso para el punto de conexión “Enumerar incidencias del repositorio” es /repos/{owner}/{repo}/issues.

Las llaves {} en una ruta de acceso indican parámetros de ruta de acceso que hay que especificar. Los parámetros de ruta modifican la ruta del punto de conexión y son necesarios en la solicitud. Por ejemplo, los parámetros de ruta de acceso para el punto de conexión “Enumerar incidencias del repositorio” son {owner} y {repo}. Para usar esta ruta de acceso en la solicitud de API, reemplaza {repo} por el nombre del repositorio donde quieras solicitar una lista de incidencias y reemplaza {owner} por el nombre de la cuenta que posee el repositorio.

encabezados

Los encabezados proporcionan información adicional sobre la solicitud y la respuesta deseada. A continuación se muestran algunos ejemplos de encabezados que puedes usar en las solicitudes a la API de REST de GitHub. Para obtener un ejemplo de solicitud que usa encabezados, consulta Realización de una solicitud.

Accept

La mayoría de puntos de conexión de la API de REST de GitHub especifican que debes pasar un encabezado Accept con un valor de application/vnd.github+json. El valor del encabezado Accept es un tipo de medio. Para más información sobre los tipos de medios, consulta Tipos de medios.

X-GitHub-Api-Version

Debes usar este encabezado para especificar una versión de la API de REST que se usará para la solicitud. Para más información, consulta Versiones de API.

User-Agent

Todas las solicitudes de API deben incluir un encabezado User-Agent válido. El encabezado User-Agent identifica el usuario o la aplicación que realiza la solicitud.

El siguiente es un ejemplo de User-Agent para una aplicación denominada Awesome-Octocat-App:

User-Agent: Awesome-Octocat-App

Las solicitudes sin un encabezado User-Agent se rechazarán. Si proporcionas un encabezado User-Agent no válido, recibirás una respuesta 403 Forbidden.

Tipos de medios

Puedes especificar uno o varios tipos de medios agregándolos al encabezado Accept de la solicitud. Para obtener más información sobre el encabezado Accept, consulta Accept.

Los tipos de medios especifican el formato de los datos que quieres consumir de la API. Los tipos de medios son específicos de los recursos, lo que les permite cambiar de forma independiente y admitir formatos que otros recursos no admiten. En la documentación de cada punto de conexión de API de REST de GitHub se describirán los tipos de medios que admite. Para obtener más información, consulta el Documentación de API REST para GitHub.

Los tipos de medios más comunes admitidos por la API de REST de GitHub son application/vnd.github+json y application/json.

Hay tipos de medios personalizados que puede usar con algunos puntos de conexión. Por ejemplo, la API de REST para administrar confirmaciones y solicitudes de cambios admite los tipos de medios diff, patch y sha. Otros puntos de conexión usan los tipos de medios full, raw, text o html.

Todos los tipos de medios personalizados para GitHub tienen este aspecto: application/vnd.github.PARAM+json, donde PARAM es el nombre del tipo de medio. Por ejemplo, para especificar el tipo de medios raw, se usaría application/vnd.github.raw+json.

Para obtener un ejemplo de una solicitud que usa tipos de medios, consulta Realización de una solicitud.

Autenticación

Muchos puntos de conexión de la API de REST necesitan autenticación o devuelven información adicional si te autenticas. Además, cuando te autenticas, puedes realizar más solicitudes por hora.

Parámetros

Muchos métodos de API requieren o permiten enviar información adicional en los parámetros de la solicitud. Hay algunos tipos diferentes de parámetros: parámetros de ruta de acceso, parámetros de cuerpo y parámetros de consulta.

Parámetros de ruta

Los parámetros de ruta modifican la ruta del punto de conexión. Estos parámetros son necesarios para la solicitud. Para más información, consulta Trazado.

Parámetros del cuerpo

Los parámetros de cuerpo permiten pasar datos adicionales a la API. Estos parámetros pueden ser opcionales u obligatorios, según el punto de conexión. Por ejemplo, un parámetro de cuerpo puede permitirte especificar un título de problema al crear un problema o especificar ciertas opciones de configuración al habilitar o deshabilitar una característica. En la documentación de cada punto de conexión de API de REST de GitHub se describirán los parámetros de cuerpo que admite. Para obtener más información, consulta el Documentación de API REST para GitHub.

Por ejemplo, el punto de conexión “Crear una incidencia” exige que especifiques un título para la nueva incidencia en tu solicitud. También permite especificar opcionalmente otra información, como el texto que se va a colocar en el cuerpo de la incidencia, los usuarios que se asignan a la nueva incidencia o las etiquetas que se aplicarán a la nueva incidencia. Para obtener un ejemplo de una solicitud que usa parámetros de cuerpo, consulta Realización de una solicitud.

Debes autenticar la solicitud para pasar parámetros de cuerpo. Para más información, consulta Autenticación.

Parámetros de consulta

Los parámetros de consulta permiten controlar qué datos se devuelven para una solicitud. Estos parámetros suelen ser opcionales. La documentación de cada endpoint de la API REST de GitHub describirá cualquier parámetro de consulta que admita. Para obtener más información, consulta el Documentación de API REST para GitHub.

Por ejemplo, el punto de conexión “Enumerar eventos públicos” devuelve treinta problemas de manera predeterminada. Puedes usar el parámetro de consulta per_page para devolver dos incidencias en lugar de 30. Puedes usar el parámetro de consulta page para capturar solo la primera página de resultados. Para obtener un ejemplo de una solicitud que usa parámetros de consulta, tendrás que consultar Realización de una solicitud.

Realización de una solicitud

gh api --method GET /octocat \
--header 'Accept: application/vnd.github+json' \
--header "X-GitHub-Api-Version: 2022-11-28"

gh api --method GET /octocat \
--header 'Accept: application/vnd.github+json' \
--header "X-GitHub-Api-Version: 2022-11-28"

gh api --method GET /events -F per_page=2 -F page=1
--header 'Accept: application/vnd.github+json' \

gh api --method GET /events -F per_page=2 -F page=1
--header 'Accept: application/vnd.github+json' \

gh api --method POST /repos/octocat/Spoon-Knife/issues \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
-f title='Created with the REST API' \
-f body='This is a test issue created by the REST API' \

gh api --method POST /repos/octocat/Spoon-Knife/issues \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
-f title='Created with the REST API' \
-f body='This is a test issue created by the REST API' \

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28"

curl --request GET \
--url "https://api.github.com/octocat" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28"

curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

curl --request GET \
--url "https://api.github.com/events?per_page=2&page=1" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/events

curl \
--request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

curl \
--request POST \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues" \
--header "Accept: application/vnd.github+json" \
--header "X-GitHub-Api-Version: 2022-11-28" \
--header "Authorization: Bearer YOUR-TOKEN" \
--data '{
  "title": "Created with the REST API",
  "body": "This is a test issue created by the REST API"
}'

Uso de la respuesta

Tras hacer una solicitud, la API devolverá el código de estado de respuesta, los encabezados de respuesta y, posiblemente, un cuerpo de la respuesta.

Acerca del código de respuesta y los encabezados

Cada solicitud devolverá un código de estado HTTP que indica el éxito de la respuesta. Para obtener más información sobre los códigos de respuesta, consulta la documentación del código de estado de respuesta HTTP de MDN.

Además, la respuesta incluirá encabezados que proporcionan más detalles sobre la respuesta. Los encabezados que comienzan por X- o x- son personalizados para GitHub. Por ejemplo, los encabezados x-ratelimit-remaining y x-ratelimit-reset indican cuántas solicitudes puede realizar en un período de tiempo.

gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/octocat/Spoon-Knife/issues \
-F per_page=2 --include

HTTP/2.0 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
Cache-Control: private, max-age=60, s-maxage=60
Content-Security-Policy: default-src 'none'
Content-Type: application/json; charset=utf-8
Date: Thu, 04 Aug 2022 19:56:41 GMT
Etag: W/"a63dfbcfdb73621e9d2e89551edcf9856731ced534bd7f1e114a5da1f5f73418"
Link: <https://api.github.com/repositories/1300192/issues?per_page=1&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=1&page=14817>; rel="last"
Referrer-Policy: origin-when-cross-origin, strict-origin-when-cross-origin
Server: GitHub.com
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
Vary: Accept, Authorization, Cookie, Accept-Encoding, Accept, X-Requested-With
X-Accepted-Oauth-Scopes: repo
X-Content-Type-Options: nosniff
X-Frame-Options: deny
X-Github-Api-Version-Selected: 2022-08-09
X-Github-Media-Type: github.v3; format=json
X-Github-Request-Id: 1C73:26D4:E2E500:1EF78F4:62EC2479
X-Oauth-Client-Id: 178c6fc778ccc68e1d6a
X-Oauth-Scopes: gist, read:org, repo, workflow
X-Ratelimit-Limit: 15000
X-Ratelimit-Remaining: 14996
X-Ratelimit-Reset: 1659645499
X-Ratelimit-Resource: core
X-Ratelimit-Used: 4
X-Xss-Protection: 0

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`)
}

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  console.log(`Success! Status: ${result.status}. Rate limit remaining: ${result.headers["x-ratelimit-remaining"]}`)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Rate limit remaining: ${error.headers["x-ratelimit-remaining"]}. Message: ${error.response.data.message}`)
}

curl --request GET \
--url "https://api.github.com/repos/octocat/Spoon-Knife/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" \
--include

HTTP/2 200
server: GitHub.com
date: Thu, 04 Aug 2022 20:07:51 GMT
content-type: application/json; charset=utf-8
cache-control: public, max-age=60, s-maxage=60
vary: Accept, Accept-Encoding, Accept, X-Requested-With
etag: W/"7fceb7e8c958d3ec4d02524b042578dcc7b282192e6c939070f4a70390962e18"
x-github-media-type: github.v3; format=json
link: <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=2>; rel="next", <https://api.github.com/repositories/1300192/issues?per_page=2&sort=updated&direction=asc&page=7409>; rel="last"
access-control-expose-headers: ETag, Link, Location, Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
access-control-allow-origin: *
strict-transport-security: max-age=31536000; includeSubdomains; preload
x-frame-options: deny
x-content-type-options: nosniff
x-xss-protection: 0
referrer-policy: origin-when-cross-origin, strict-origin-when-cross-origin
content-security-policy: default-src 'none'
x-ratelimit-limit: 15000
x-ratelimit-remaining: 14996
x-ratelimit-reset: 1659645535
x-ratelimit-resource: core
x-ratelimit-used: 4
accept-ranges: bytes
content-length: 4936
x-github-request-id: 14E0:4BC6:F1B8BA:208E317:62EC2715

Acerca del cuerpo de la respuesta

Muchos puntos de conexión devolverán un cuerpo de la respuesta. A menos que se especifique lo contrario, el cuerpo de la respuesta está en formato JSON. Los campos vacíos se incluyen como valores null en lugar de omitirse. Todas las marcas de tiempo se devuelven en hora UTC, formato ISO 8601: YYYY-MM-DDTHH:MM:SSZ.

A diferencia de GraphQL API donde se especifica la información que deseas, la API de REST normalmente devuelve más información de la que necesitas. Si lo deseas, puedes analizar la respuesta para extraer fragmentos de información específicos.

gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/REPO-OWNER/REPO-NAME/issues \
-F per_page=2 > data.json

gh api \
--header 'Accept: application/vnd.github+json' \
--method GET /repos/REPO-OWNER/REPO-NAME/issues \
-F per_page=2 > data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}

try {
  const result = await octokit.request("GET /repos/{owner}/{repo}/issues", {
    owner: "REPO-OWNER",
    repo: "REPO-NAME",
    per_page: 2,
  });

  const titleAndAuthor = result.data.map(issue => {title: issue.title, authorID: issue.user.id})

  console.log(titleAndAuthor)

} catch (error) {
  console.log(`Error! Status: ${error.status}. Message: ${error.response.data.message}`)
}

curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

curl --request GET \
--url "https://api.github.com/repos/REPO-OWNER/REPO-NAME/issues?per_page=2" \
--header "Accept: application/vnd.github+json" \
--header "Authorization: Bearer YOUR-TOKEN" > data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

jq '.[] | {title: .title, authorID: .user.id}' data.json

{
  "title": "Update index.html",
  "authorID": 10701255
}
{
  "title": "Edit index file",
  "authorID": 53709285
}

Representaciones detalladas frente a resumen

Una respuesta puede incluir todos los atributos de un recurso o solo un subconjunto de atributos, en función de si se captura un recurso individual o una lista de recursos.

• Al capturar un recurso individual, como un repositorio específico, la respuesta suele incluir todos los atributos para ese recurso. Es la representación "detallada" del recurso.
• Al capturar una lista de recursos, como una lista de varios repositorios, la respuesta solo incluirá un subconjunto de los atributos de cada recurso. Esta es la representación resumida del recurso.

Ten en cuenta que, en ocasiones, la autorización influye en la cantidad de detalles que se incluyen en la representación.

El motivo de esto es que, para proporcionar algunos atributos, la API requiere realizar muchos cálculos, por lo que GitHub excluye esos atributos de la representación de resumen. Para obtener estos atributos, puedes recuperar la representación detallada.

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.

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"

Pasos siguientes

En este artículo se ha mostrado cómo enumerar y crear propuestas en un repositorio. Para más práctica, intenta comentar una propuesta, edita el título de una propuesta o cierra una propuesta. Para obtener más información sobre estas operaciones, consulta el punto de conexión “Crear un comentario de incidencia” y “Actualizar una incidencia”.

Para obtener más información sobre otros puntos de conexión que puedes usar, consulta la documentación de referencia de REST.