Procedimientos recomendados para usar la API de REST

Evitar sondeos

Debes suscribirte a eventos de webhook en lugar de sondear la API para obtener datos. Esto ayudará a que la integración permanezca dentro del límite de frecuencia de API. Para más información, consulta Documentación de webhooks.

Si no puede usar webhooks y debe sondear la API, sondee lo más eficaz posible para evitar superar el límite de velocidad:

Sondee solo con tanta frecuencia como sea necesario, según una programación fija. Si una respuesta incluye una cabecera x-poll-interval, espere al menos ese número de segundos antes de volver a consultar el mismo punto de conexión.
Realice solicitudes condicionales autenticadas, de modo que los datos que no hayan cambiado no cuenten para su límite principal de solicitudes. Para obtener más información, consulte Uso de solicitudes condicionales.
Solicite solo los datos que necesita y mantenga estables las respuestas, de modo que más sondeos devuelvan 304 Not Modified. Para obtener más información, consulte Realización de solicitudes que se pueden almacenar en caché.

Realizar solicitudes autenticadas

Las solicitudes autenticadas tienen una limitación de volumen principal mayor que las solicitudes no autenticadas. Para evitar superar la limitación de volumen, debes realizar solicitudes autenticadas. Para más información, consulta Límites de tasa de la API REST.

Evitar solicitudes simultáneas

Para evitar superar las limitaciones de volumen secundarias, debes realizar solicitudes en serie en lugar de simultáneas. Para ello, puedes implementar un sistema de colas para las solicitudes.

Pausar entre solicitudes mutativas

Si estás realizando una gran cantidad de POST, PATCH, PUT o DELETE solicitudes, espera al menos un segundo entre una solicitud y otra. Esto te ayudará a evitar los límites de tasa secundarios.

Manejar adecuadamente los errores de límites de tasa

Si recibe un error de limitación de volumen, debe dejar de realizar solicitudes temporalmente según estas directrices:

Si el encabezado de respuesta retry-after está presente, no debes reintentar la solicitud hasta que hayan transcurrido los segundos indicados.
Si el encabezado x-ratelimit-remaining es 0, no realice otra solicitud hasta después de la hora especificada en el encabezado x-ratelimit-reset. El encabezado x-ratelimit-reset está en segundos de época UTC.
De lo contrario, espere al menos un minuto antes de volver a intentarlo. Si la solicitud sigue produciendo un error debido a una limitación de volumen secundaria, espere un período de tiempo exponencialmente creciente entre reintentos y genere un error después de un número específico de reintentos.

Continuar realizando solicitudes mientras tiene una limitación de volumen puede dar lugar a la prohibición de la integración.

Seguir redireccionamientos

La GitHub API REST usa el redireccionamiento HTTP cuando corresponda. Debes asumir que cualquier solicitud podría resultar en un redireccionamiento. La recepción de un redireccionamiento HTTP no es un error y debes seguir esa redirección.

Un código de estado 301 indica un redireccionamiento permanente. Debes repetir la solicitud en la dirección URL especificada por el encabezado location. Además, debes actualizar el código para usar esta dirección URL para futuras solicitudes.

Un código de estado 302 o 307 indica un redireccionamiento temporal. Debes repetir la solicitud en la dirección URL especificada por el encabezado location. Sin embargo, no debes actualizar el código para usar esta dirección URL para futuras solicitudes.

Pueden utilizarse otros códigos de estado de redirección de acuerdo con las especificaciones HTTP.

No analices manualmente las direcciones URL

Muchos puntos de conexión de API entregan valores de dirección URL para los campos del cuerpo de la respuesta. No debes intentar analizar estas direcciones URL ni predecir la estructura de direcciones URL futuras. Esto puede hacer que la integración se interrumpa si GitHub cambia la estructura de la dirección URL en el futuro. En su lugar, debes buscar un campo que contenga la información que necesitas. Por ejemplo, el punto de conexión para crear un asunto entrega un campo html_url con un valor como https://github.com/octocat/Hello-World/issues/1347 y un campo number con un valor como 1347. Si necesitas saber el número del problema, usa el campo number en lugar de analizar el campo html_url.

Del mismo modo, no debes intentar construir manualmente consultas de paginación. En su lugar, debes usar los encabezados de vínculo para determinar qué páginas de resultados puedes solicitar. Para más información, consulta Uso de la paginación en la API de REST.

Uso de solicitudes condicionales

La mayoría de los puntos de conexión entregan un encabezado etag y muchos puntos de conexión entregan un encabezado last-modified. Puedes usar los valores de estos encabezados para realizar solicitudes GET condicionales. Si la respuesta no ha cambiado, recibirás una respuesta 304 Not Modified. La realización de una solicitud condicional no cuenta para el límite de frecuencia principal si se devuelve una respuesta 304 y la solicitud se realizó mientras se autorizaba correctamente con un encabezado Authorization. Esto hace que las solicitudes condicionales sean especialmente útiles al sondear un punto de conexión, ya que cada 304 Not Modified respuesta es rápida y no usa el límite de velocidad.

En los ejemplos siguientes, reemplace por YOUR-TOKEN el token de acceso.

Para realizar una solicitud condicional con :etag

Realice una solicitud y guarde el valor del etag encabezado de la respuesta.

curl --include --header "Authorization: Bearer YOUR-TOKEN" https://api.github.com/repos/octocat/Spoon-Knife/pulls

La respuesta incluye un etag encabezado:

HTTP/2 200
etag: "644b5b0155e6404a9cc4bd9d8b1ae730"

En la siguiente solicitud a la misma URL, envía el valor guardado en la cabecera if-none-match.
```
curl --include --header "Authorization: Bearer YOUR-TOKEN" --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"' https://api.github.com/repos/octocat/Spoon-Knife/pulls
```
Si los datos no han cambiado, recibirá una 304 Not Modified respuesta, que no cuenta con respecto al límite de velocidad principal:
```
HTTP/2 304
```

También puede usar el last-modified encabezado . Por ejemplo, si una solicitud anterior entregó un valor de encabezado last-modified de Wed, 25 Oct 2023 19:17:59 GMT, puedes usar el encabezado if-modified-since en una solicitud futura:

curl --include --header "Authorization: Bearer YOUR-TOKEN" --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT' https://api.github.com/repos/octocat/Spoon-Knife

No se admiten solicitudes condicionales para métodos no seguros, como POST, PUT, PATCHy DELETE , a menos que se indique lo contrario en la documentación de un punto de conexión específico.

Realización de solicitudes que se pueden almacenar en caché

Una solicitud condicional solo ahorra tiempo y límite de velocidad si el punto de conexión devuelve 304 Not Modified. El extremo devuelve 304 cuando la representación que solicitaste no ha cambiado desde que guardaste su valor etag o last-modified; los encabezados de respuesta no relacionados, como la fecha, pueden seguir siendo distintos. Para que 304 las respuestas sean más probables al sondear, mantenga las solicitudes estables y específicas.

Solicite solo los datos que necesite. Una respuesta más pequeña y específica cambia con menos frecuencia, por lo que devuelve 304 Not Modified más a menudo. Por ejemplo, para comprobar las solicitudes de incorporación de cambios de una rama, filtre la lista por esa rama en lugar de enumerar cada solicitud de incorporación de cambios y busque los resultados usted mismo. Reemplace HEAD-OWNER por la cuenta a la que pertenece la rama principal; para una solicitud de extracción procedente de una bifurcación, esta es la cuenta a la que pertenece la bifurcación. Sustituya BRANCH-NAME por el nombre de la rama y codifíquelo para URL si contiene caracteres especiales como # o &:

curl --include --header "Authorization: Bearer YOUR-TOKEN" "https://api.github.com/repos/octocat/Spoon-Knife/pulls?head=HEAD-OWNER:BRANCH-NAME"

Si pagina una lista, utilice un orden estable. Algunos parámetros, como sort=updated, reordenar la lista cada vez que cambia un elemento. Cuando un elemento se mueve a una nueva posición, los elementos entre sus posiciones antiguas y nuevas cambian a páginas diferentes, por lo que las páginas que ya ha capturado pueden devolver nuevos datos en lugar de 304 Not Modified. Un orden estable, como el predeterminado, detiene las actualizaciones de los elementos existentes para reordenar la lista, aunque agregar o quitar elementos todavía puede desplazar las entradas a otras páginas.

Use los mismos parámetros cada vez que sondee los mismos datos. Un tamaño de página diferente, un número de página o un filtro genera una respuesta diferente con otro etag.

No omitas errores

No debes omitir los códigos de error 4xx y 5xx repetidos. En su lugar, debes asegurarte de que estás interactuando correctamente con la API. Por ejemplo, si un punto de conexión solicita una cadena y estás enviando un valor numérico, vas a recibir un error de validación. De forma similar, intentar acceder a un punto de conexión inexistente o no autorizado dará como resultado un error 4xx.

Si está realizando sondeos y un recurso devuelve repetidamente una respuesta 404 Not Found, no siga solicitándolo en cada sondeo. En primer lugar, asegúrese de que 404 no se deba a la autenticación o la autorización. GitHub devuelve una 404 Not Found respuesta en lugar de una 403 Forbidden respuesta para algunos recursos privados cuando las credenciales no conceden acceso, por lo que un 404 no siempre significa que el recurso está ausente. Para más información, consulta Solución de problemas de API de REST. Una vez que haya confirmado que las credenciales son correctas, espere mucho más tiempo antes de volver a comprobarlo o vuelva a comprobarlo solo cuando tenga una razón para creer que el recurso ya existe. Solicitar repetidamente un recurso que falta desperdicia el límite de velocidad y puede desencadenar un límite de velocidad secundario.

El ignorar los errores de validación constantes a propóstio podría resultar en la suspensión de tu app por abuso.