{"meta":{"title":"Procedimientos recomendados para usar la API de REST","intro":"Siga estos procedimientos recomendados al usar la API de GitHub.","product":"REST API","breadcrumbs":[{"href":"/es/rest","title":"REST API"},{"href":"/es/rest/using-the-rest-api","title":"Mediante la API de REST"},{"href":"/es/rest/using-the-rest-api/best-practices-for-using-the-rest-api","title":"procedimientos recomendados"}],"documentType":"article"},"body":"# Procedimientos recomendados para usar la API de REST\n\nSiga estos procedimientos recomendados al usar la API de GitHub.\n\n## Evitar sondeos\n\nDebes 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](/es/webhooks).\n\nSi no puede usar webhooks y debe sondear la API, sondee lo más eficaz posible para evitar superar el límite de velocidad:\n\n* 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.\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](#use-conditional-requests).\n* 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é](#make-requests-that-can-be-cached).\n\n## Realizar solicitudes autenticadas\n\nLas 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](/es/rest/using-the-rest-api/rate-limits-for-the-rest-api).\n\n## Evitar solicitudes simultáneas\n\nPara 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.\n\n## Pausar entre solicitudes mutativas\n\nSi 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.\n\n## Manejar adecuadamente los errores de límites de tasa\n\nSi recibe un error de limitación de volumen, debe dejar de realizar solicitudes temporalmente según estas directrices:\n\n* Si el encabezado de respuesta `retry-after` está presente, no debes reintentar la solicitud hasta que hayan transcurrido los segundos indicados.\n* 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.\n* 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.\n\nContinuar realizando solicitudes mientras tiene una limitación de volumen puede dar lugar a la prohibición de la integración.\n\n## Seguir redireccionamientos\n\nLa 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.\n\nUn 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.\n\nUn 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.\n\nPueden utilizarse otros códigos de estado de redirección de acuerdo con las especificaciones HTTP.\n\n## No analices manualmente las direcciones URL\n\nMuchos 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`.\n\nDel 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](/es/rest/using-the-rest-api/using-pagination-in-the-rest-api).\n\n## Uso de solicitudes condicionales\n\nLa 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.\n\nEn los ejemplos siguientes, reemplace por `YOUR-TOKEN` el token de acceso.\n\nPara realizar una solicitud condicional con :`etag`\n\n1. Realice una solicitud y guarde el valor del `etag` encabezado de la respuesta.\n\n   ```shell\n   curl --include --header \"Authorization: Bearer YOUR-TOKEN\" https://api.github.com/repos/octocat/Spoon-Knife/pulls\n   ```\n\n   La respuesta incluye un `etag` encabezado:\n\n   ```text\n   HTTP/2 200\n   etag: \"644b5b0155e6404a9cc4bd9d8b1ae730\"\n   ```\n\n2. En la siguiente solicitud a la misma URL, envía el valor guardado en la cabecera `if-none-match`.\n\n   ```shell\n   curl --include --header \"Authorization: Bearer YOUR-TOKEN\" --header 'if-none-match: \"644b5b0155e6404a9cc4bd9d8b1ae730\"' https://api.github.com/repos/octocat/Spoon-Knife/pulls\n   ```\n\n   Si los datos no han cambiado, recibirá una `304 Not Modified` respuesta, que no cuenta con respecto al límite de velocidad principal:\n\n   ```text\n   HTTP/2 304\n   ```\n\nTambié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:\n\n```shell\ncurl --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\n```\n\nNo se admiten solicitudes condicionales para métodos no seguros, como `POST`, `PUT`, `PATCH`y `DELETE` , a menos que se indique lo contrario en la documentación de un punto de conexión específico.\n\n## Realización de solicitudes que se pueden almacenar en caché\n\nUna 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.\n\nSolicite 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 `&`:\n\n```shell\ncurl --include --header \"Authorization: Bearer YOUR-TOKEN\" \"https://api.github.com/repos/octocat/Spoon-Knife/pulls?head=HEAD-OWNER:BRANCH-NAME\"\n```\n\nSi 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.\n\nUse 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`.\n\n## No omitas errores\n\nNo 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`.\n\nSi 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.\nGitHub 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](/es/rest/using-the-rest-api/troubleshooting-the-rest-api#404-not-found-for-an-existing-resource). 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.\n\nEl ignorar los errores de validación constantes a propóstio podría resultar en la suspensión de tu app por abuso.\n\n## Información adicional\n\n* [Procedimientos recomendados para usar webhooks](/es/webhooks/using-webhooks/best-practices-for-using-webhooks)\n* [Procedimientos recomendados para crear una aplicación de GitHub](/es/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)"}