Nota: Las limitaciones de volumen solo están habilitadas para la instancia si el administrador del sitio las ha habilitado. Incluso si las limitaciones de volumen están deshabilitadas para la instancia, puede seguir los procedimientos recomendados que están diseñados para ayudarte a evitar superar la limitación de volumen. Esto puede ayudar a reducir la carga en los servidores.
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».
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 obtener más información, vea «Límites de volumen de la API de 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 las limitaciones de volumen secundarias.
Gestión adecuada de errores de limitaciones de volumen
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-afterestá presente, no debes reintentar la solicitud hasta que hayan transcurrido los segundos indicados. - Si el encabezado
x-ratelimit-remaininges0, no realice otra solicitud hasta después de la hora especificada en el encabezadox-ratelimit-reset. El encabezadox-ratelimit-resetestá 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 API REST de GitHub Enterprise Server 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 obtener más información, vea «Uso de la paginación en la API de REST».
Usa solicitudes condicionales si procede
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 condicionales. Si la respuesta no ha cambiado, recibirás una respuesta 304 Not Modified. La realización de una solicitud condicional no cuenta con la limitación de volumen principal si se entrega una respuesta 304.
Por ejemplo, si una solicitud anterior entregó un valor de encabezado etag de 644b5b0155e6404a9cc4bd9d8b1ae730, puedes usar el encabezado if-none-match en una solicitud futura:
curl http(s)://HOSTNAME/api/v3/meta --include --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
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 http(s)://HOSTNAME/api/v3/repos/github/docs --include --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT'
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.
El ignorar los errores de validación constantes a propóstio podría resultar en la suspensión de tu app por abuso.