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 obtener más información, vea «Documentación de webhooks».

Sigue cualquier redireccionamiento que te envíe la API

GitHub es muy explícito en decirte cuando un recurso se migró y lo hace proporcionándote un código de estado de redirección. Debes seguir estas redirecciones. Cada respuesta de redirección establece el encabezado Location con el nuevo identificador URI que se debe visitar. Si recibes una redirección, es mejor que actualices tu código para seguir a la nueva URI, en caso de que estés utilizando una ruta obsoleta que tal ves eliminemos.

Hemos proporcionado una lista de códigos de estado HTTP que se deben tener en cuenta al diseñar la aplicación para seguir los redireccionamientos.

No analices las URL manualmente

A menudo, las respuestas a la API contienen datos en forma de URL. Por ejemplo, cuando solicitamos un repositorio, estamos enviando una clave denominada clone_url con la URL que puede utilizar para clonar el repositorio.

Para mantener la estabilidad de tu app, no deberías analizar estos datos o tratr de adivinar y construir el formato de las URL futuras. Tu app puede fallar si decidimos cambiar la URL.

Por ejemplo, al trabajar con resultados paginados, a menudo resulta tentador construir direcciones URL a las que se anexa ?page=<number> al final. Evita esa tentación. Para obtener más información sobre los resultados paginados de seguimiento fiables, consulta "Uso de la paginación en la API de REST".

Lidiar con los límites de tasa

El límite de frecuencia de la API de GitHub garantiza que la API sea rápida y esté disponible para todos los usuarios.

Si llegas a un límite de frecuencia, debes dejar de realizar solicitudes hasta después del tiempo que se especifica en el encabezado x-ratelimit-reset. Si no lo haces, se podría prohibir tu integración. Para obtener más información, vea «Recursos en la API de REST».

Lidiar con límites de tasa secundarios

GitHub también puede usar límites de frecuencia secundarios para garantizar la disponibilidad de la API. Para obtener más información, vea «Recursos en la API de REST».

Para evitar llegar a este límite, deberás asegurarte de que tu aplicación siga los siguientes lineamientos.

Hacer solicitudes autenticadas, o utilizar la ID de cliente y secreto de tu aplicación. Las solicitudes sin autenticar están sujetas a una limitación de frecuencia secundaria más estricta.
Hacer solicitudes en serie para solo un usuario o ID de cliente. No realice solicitudes para un solo usuario o id. de cliente simultáneamente.
Si está realizando una gran cantidad de POST, PATCH, PUT o solicitudes de DELETE para un único usuario o id. de cliente, espere al menos un segundo entre una solicitud y otra.
Si se te ha impuesto un límite, espera antes de volver a intentar la solicitud.
- Si está presente el encabezado de respuesta Retry-After, vuelve a intentar la solicitud después del tiempo que se especifica en el encabezado. El valor del encabezado Retry-After siembre será un número entero, el cual representará la cantidad de segundos que debe esperar antes de volver a realizar la solicitud. Por ejemplo, Retry-After: 30 significa que debe esperar 30 segundos antes de enviar más solicitudes.
- Si el encabezado de x-ratelimit-remaining es 0, vuelve a intentar la solicitud después del tiempo que se especifica en el encabezado x-ratelimit-reset. El encabezado x-ratelimit-reset siempre será un entero que representa la hora a la que se restablece la ventana de límite de frecuencia actual en segundos UTC.
- De lo contrario, espera una cantidad de tiempo exponencialmente creciente entre reintentos y genera un error después de un número específico de reintentos.

GitHub se reserva el derecho de cambiar estas directrices según sea necesario para garantizar la disponibilidad.

Lidiar con los errores de la API

Aunque tu código jamás introducirá un error, podrías encontrarte con que has dado con varios errores sucesivos cuando intentas acceder a la API.

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

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