Guías prácticas detalladas

Consultar una API pública y conservar una extracción verificable

Defina consulta, paginación, errores y respuesta original antes de transformar los datos.

Actualización :

Portátil y tableta con una respuesta API esquemática y una fila que revisar antes de importar. Escena ilustrativa.

Ilustración generada por IA

¿Cómo reproducir una extracción sin exagerar su cobertura?

Una API responde a una consulta en un esquema y un momento concretos. No demuestra que se haya solicitado toda la base ni que permanezca estable entre llamadas. Separe el registro de la recogida del análisis.

  1. Elegir acceso

    Lea documentación oficial: versión, alcance, condiciones, autenticación y límites. Para toda una base, busque exportación oficial.

  2. Consultar poco

    Anote endpoint, método, parámetros, filtros y orden. Prefiera identificadores. Nunca publique claves o tokens.

  3. Inspeccionar respuesta

    Guarde estado HTTP, hora, formato y errores. Compruebe campos y unidades; HTTP 200 puede contener vacío o error funcional.

  4. Paginar

    Revise total, páginas y cursores. Cuente filas e identificadores únicos y anote duplicados y condición de parada. La base puede cambiar durante la recogida.

  5. Conservar original

    Guarde respuesta y huella; documente limpieza, filtros y conversiones. No publique datos personales o secretos en registros públicos.

  6. Gestionar cambios

    Respete indicaciones de reintento ante 429 o indisponibilidad. Otra extracción es otra observación: compare también esquema y selección.

Ejemplos de consultas mínimas

Ilustran la sintaxis; compruebe disponibilidad, autenticación y condiciones en la documentación.

Taller de lectura

Un registro de revalidación, no una extracción vacía nueva

Los intercambios HTTP DEMO son ficticios. Este apartado no contacta servidores ni reintenta peticiones.

Datos y registros ficticios para aprender: ninguno de estos resultados procede de una consulta en directo.

Separar copia, validación y límite de peticiones

El cliente conserva una representación para area=A con su ETag. La política ficticia limita los intentos a dos. No garantiza disponibilidad del servicio.

  1. Guardar la primera copia

    Intercambio ficticio
    GET area=A → 200, cuerpo y ETag "demo-v1"
    Estado conservado
    Cuerpo vinculado a la petición exacta
    Decisión del escenario
    Conservar juntos filtros, versión y representación.
  2. Revalidar la misma selección

    Intercambio ficticio
    Misma petición con If-None-Match → 304 sin cuerpo
    Estado conservado
    Existe una copia correspondiente
    Decisión del escenario
    Reutilizarla; no registrar una extracción de cero filas.
  3. Cambiar selección

    Intercambio ficticio
    Nueva petición area=B
    Estado conservado
    La copia A no documenta B
    Decisión del escenario
    Tratar por separado aunque el texto ETag se parezca.
  4. Alcanzar un límite

    Intercambio ficticio
    429; Retry-After: 15
    Estado conservado
    Intento fallido, no resultado cero
    Decisión del escenario
    Esperar según indicación; al llegar a dos intentos, parar y registrar.

¿Qué registro separa correctamente los estados de recogida?

Abra cada propuesta para comparar su diagnóstico. Pueden seguir siendo necesarios otros controles.

304: nueva selección vacía

No. El escenario sigue usando la copia de la misma selección. Cuerpo ausente no significa tabla vacía.

Copiar datos de A en la extracción de B

No. Cambia silenciosamente el ámbito de las observaciones. Los parámetros forman parte del registro.

Guardar la referencia a la copia A y registrar aparte la parada por límite

Sí. El registro debe identificar los datos usados y los intentos sin una nueva extracción.

Registro ficticio del cliente

Selección: GET /demo?area=A
Copia: cuerpo guardado; ETag="demo-v1"
Condición: If-None-Match="demo-v1"
Respuesta: 304; referencia a copia A
Otro intento: 429; Retry-After=15 segundos
Política DEMO: dos intentos máximo, después parar
Derechos de republicación: comprobar aparte

La cota de dos intentos es del ejemplo, no de los RFC. Sin copia utilizable no invente contenido; prepare otra recuperación conforme a la política del servicio.

Documentación de las reglas, separada de los ejemplos ficticios

Comparar otras situaciones y ejercicios

Solo una página

Compruebe total y siguiente cursor antes de presentar un recuento completo.

Ausencia convertida en cero

Distinga null, campo ausente, lista vacía y cero; afectan promedios.

Consulta igual, cifras nuevas

Eurostat documenta una base con versiones más recientes. Conserve extracciones fechadas para reproducir cálculos.

Ejercicio resuelto

Estado 200 con un error de aplicación

Ejemplo ficticio: los valores y documentos permiten aprender el método y no describen una organización real.

El contrato de esta API ficticia exige success=true antes del tratamiento. Examine por separado respuesta HTTP, estado de aplicación y presencia de resultados.

Si la tabla supera la pantalla, desplácela horizontalmente; las flechas funcionan cuando la zona tiene el foco.

Datos iniciales
ElementoInformación observada
Estado HTTP200
Indicador de aplicaciónsuccess=false
Mensaje recibidoMensaje: cuota alcanzada
Matriz de resultadosNo se proporciona matriz

Comprobaciones

  1. Comprobar estado HTTP e indicador por separado.
  2. Verificar presencia del esquema esperado.
  3. Guardar el error sin publicar un recuento falso.
Leer la solución

Solución y decisión

El transporte respondió, pero la recopilación falló según el contrato. No se establece un recuento cero. Marcar fallo y seguir la regla documentada de reintento; no fabricar tabla vacía para continuar el cálculo.

Si cambia el caso

Si una respuesta exitosa contiene realmente una tabla vacía, puede establecerse cero para la consulta y ámbito indicados. Repetir con success=true y un cuerpo JSON truncado: ni estado ni indicador bastan. Rechazar el lote incompleto, conservar el punto de recuperación y comprobar que ningún valor parcial sustituya la última extracción validada.

Registro que conservar

Guardar consulta sin secretos, estado, error, contrato y situación de reintento.

Referencia documental : IETF — RFC 9110, 200 OK · Consultada el

REFERENCIAS DOCUMENTADAS

Wikidata: truthy selecciona rango, no verdad certificada

Truthy es una proyección técnica por entidad y propiedad: si hay declaraciones preferidas excluye las normales; de lo contrario usa las normales. No vota fuentes ni elige la fecha máxima.

Wikidata: truthy selecciona rango, no verdad certificada
ReferenciaValor o formaQué identifica
PreferredRankPreferredSelecciona todas las preferidas del par. Preferido no implica unicidad.
NormalRankNormalSelecciona normales solo sin preferidas para ese par. Varios valores normales pueden ser legítimos.
DeprecatedRankDeprecatedExcluye las desaconsejadas de truthy; siguen disponibles completas para documentar errores o rechazos.
wdt:Best non-deprecated rankEl camino directo usa mejores rangos no desaconsejados sin calificadores. No garantiza actualidad, integridad o respaldo.
wikibase:BestRankFull statement selectionEste tipo selecciona nodos completos de mejor rango y conserva acceso a calificadores y referencias.
ScopeEntity + propertyLa regla depende de entidad y propiedad. Preferir población no selecciona fundación, nombre u otra propiedad.

Qué conservar en el expediente

Si todas están desaconsejadas, no invente una vuelta a ellas. Para desacuerdos o historia lea declaraciones completas y rangos. Ausencia en consulta directa puede deberse al filtro.

¿Un valor wdt: es necesariamente el más reciente?

No. Rango y tiempo son mecanismos distintos. Compruebe fecha y criterio de rango; pueden coexistir varias preferidas.

Documentación primaria

Documentación consultada el .

REFERENCIAS DOCUMENTADAS

API del Banco Mundial: distinguir tres fechas y recuperar la unidad

Una respuesta JSON contiene más que un valor. El extracto real corresponde a la densidad finlandesa de 2023. Su cabecera indica una actualización WDI el 8 de octubre de 2026; esta copia se obtuvo el 23 de octubre. Las tres fechas responden a preguntas distintas.

date2023lastupdated2026-10-08extracted2026-10-23
API del Banco Mundial: distinguir tres fechas y recuperar la unidad
ReferenciaValor o formaQué identifica
date2023Año de observación. No pasa a ser 2026 porque se haya consultado en 2026.
lastupdated2026-10-08Fecha de actualización indicada en la cabecera. No acredita por sí sola una revisión de este valor concreto.
extracted2026-10-23Fecha de creación del extracto local; no sustituye al período observado ni a la fecha de la fuente.
unit""El campo unit está vacío. La definición de EN.POP.DNST especifica personas por km² de tierra: vacío no significa adimensional.
decimal / value0 / 18.3705454665088decimal vale cero aunque value contiene decimales. Conserve el valor recibido; no interprete ese campo como margen de error.
pages / total1 / 4Las cuatro observaciones caben en una página. Otra consulta puede estar paginada: compruebe pages y total antes de considerar completa la recopilación.

Consulta exacta · densidad

https://api.worldbank.org/v2/country/FRA;DEU;ESP;FIN/indicator/EN.POP.DNST?date=2023&format=json&per_page=100

Cabecera y observación FIN conservadas

[
    {
        "page": 1,
        "pages": 1,
        "per_page": 100,
        "total": 4,
        "sourceid": "2",
        "lastupdated": "2026-10-08"
    },
    [
        {
            "indicator": {
                "id": "EN.POP.DNST",
                "value": "Population density (people per sq. km of land area)"
            },
            "country": {
                "id": "FI",
                "value": "Finland"
            },
            "countryiso3code": "FIN",
            "date": "2023",
            "value": 18.3705454665088,
            "unit": "",
            "obs_status": "",
            "decimal": 0
        }
    ]
]

Qué conservar en el expediente

Es una copia fechada de la API, sin actualización automática al cargar la página. Compartir código de país no prueba una cobertura territorial idéntica. Para reproducir el análisis, conserve consulta, definiciones y valores ausentes; no transforme null en cero.

Documentación primaria

Documentación consultada el .

REFERENCIAS DOCUMENTADAS

Parámetros de formulario: conservar espacios, signos + y nombres repetidos

Una lista de parámetros es una secuencia ordenada de pares nombre-valor. Puede repetir el mismo nombre. La herramienta aplica application/x-www-form-urlencoded mediante URLSearchParams a dos valores de una línea y relee el resultado; no envía ningún formulario.

tag → C++ & IAtag → ététag=C%2B%2B+%26+IA&tag=%C3%A9t%C3%A9getAll("tag") → ["C++ & IA", "été"]
Parámetros de formulario: conservar espacios, signos + y nombres repetidos
ReferenciaValor o formaQué identifica
U+0020+Un espacio U+0020 se serializa como + en este formato. No es una regla universal para todos los componentes de una URL.
+%2BUn signo + perteneciente al valor se convierte en %2B. Pegar C++ directamente en una cadena ya codificada haría interpretar sus dos signos como espacios.
&%26Un & dentro del valor se convierte en %26 y no introduce otro parámetro.
=%3DUn = dentro del valor se convierte en %3D; el separador estructural entre nombre y valor sigue siendo =.
été%C3%A9t%C3%A9Los caracteres no ASCII se codifican a partir de UTF-8. Los escapes representan bytes, no una cantidad de letras visibles.
append / get / getAll / setordered pairsappend conserva otra aparición. get devuelve el primer valor; getAll devuelve todos en orden. set reemplaza el primero y elimina las demás apariciones de ese nombre.

Explorar dos parámetros con el mismo nombre

Dos valores de demostración calculados en esta página.

Dos pares conservados en su orden.

Serialización

tag=C%2B%2B+%26+IA&tag=%C3%A9t%C3%A9

Valores recuperados con getAll

["C++ & IA","été"]

Primer valor con get

"C++ & IA"

Qué conservar en el expediente

Codificar no es cifrar ni sanear HTML. Esta demostración no simula la selección de controles, archivos multipart ni la normalización de saltos de línea del formulario. El servidor debe definir cómo tratar parámetros repetidos; convertirlos demasiado pronto en objeto puede perder valores.

Documentación primaria

Documentación consultada el .

Prueba que conservar

  • Servicio, versión y parámetros sin secretos.
  • Hora, estado, formato, páginas y parada.
  • Respuesta original, identificadores y huella.
  • Transformaciones, unidades y límites.

Referencias oficiales

Fichas de fuentes relacionadas

Protocolos relacionados

Comprobaciones antes de concluir

  • ¿Puede reconstruir la selección sin secretos?
  • ¿El recuento contempla páginas y duplicados?
  • ¿Separa original y datos limpios?

Preguntas frecuentes

¿HTTP 200 demuestra exhaustividad?

No. Revise cuerpo, filtros, total y páginas.

¿Debe descargar toda la base?

No. Elija un alcance útil y documentado.

¿La huella garantiza cifras?

Compara bytes conservados. Método y calidad exigen sus propios controles.

¿Cómo recuperar una recogida interrumpida?

Conservar la última etapa confirmada, los parámetros y las referencias de continuación. La recuperación debe comprobar las duplicidades y posibles cambios de los datos en lugar de suponer una simple adición de las respuestas.

REFERENCIAS DOCUMENTADAS

Escrituras HTTP: comprobar la versión antes de sustituir un documento

Dos personas pueden leer una versión y enviar correcciones distintas. Una precondición permite rechazar una escritura basada en una representación anterior. Los casos son ficticios: v1 y v2 son etiquetas didácticas, no observaciones de un servicio.

GET → "v1"ETag: "v2"PUT → 412If-Match: "v1" ≠ ETag: "v2"

Lectura → cambio concurrente → escritura rechazada: ejemplo ficticio.

Escrituras HTTP: comprobar la versión antes de sustituir un documento
ReferenciaValor o formaQué identifica
PUT · If-Match: "v1"ETag: "v2" → 412El documento cambió después de su lectura. La comparación fuerte falla para este PUT: no sustituir la versión actual. Leerla de nuevo y revisar las diferencias.
PUT · If-Match: "v2"ETag: "v2" → ✓Las etiquetas fuertes coinciden: esta precondición permite continuar. No garantiza una respuesta 200 ni superar los demás controles.
PUT · If-Match: W/"v2"ETag: "v2" → 412El texto opaco coincide, pero una etiqueta es débil. If-Match exige comparación fuerte y falla. Eliminar W/ en el cliente no crea un validador fuerte.
PUT · If-None-Match: *Presente → 412 / Ausente → ✓En una escritura, el asterisco exige que no exista representación actual. Si existe, la condición falla; si no existe, el tratamiento puede continuar.
GET · If-None-Match: W/"v2"ETag: "v2" → 304Con GET o HEAD, If-None-Match usa comparación débil. Una coincidencia conduce a 304: reutilizar la copia guardada sin recibir otro cuerpo.
428Precondition RequiredEl servidor exige una petición condicional. La ausencia de condición difiere de 412, que indica una condición falsa. Una respuesta 428 no debe almacenarse en caché.

Probar una precondición

Cambie método, estado y condición. Introduzca una etiqueta entre comillas, una lista separada por comas o * solo. La evaluación se realiza en su navegador. Con * o una representación ausente, no se usa el ETag actual.

412: condición falsa. No ejecutar la operación solicitada.

Simulación didáctica local: no se envían peticiones API ni se guardan datos.

Qué conservar en el expediente

El ejercicio evalúa una sola precondición antes de actuar. Supone una petición aceptable en los demás aspectos y excluye el caso especial de una operación ya completada. Siguen siendo necesarios autenticación, autorización, validación y reglas de negocio. Para evitar sobrescrituras, la API debe comprobar y aplicar el cambio de forma atómica.

Documentación primaria

Documentación consultada el .

PROFUNDIZACIÓN / PRÁCTICA

Conservar una consulta reproducible

Una API proporciona datos útiles, pero el resultado depende de la configuración y la página. La colección debe conservar la solicitud completa y las condiciones necesarias para comprender la respuesta.

Actualizado el .

Comprobaciones prioritarias

Relever URL, parámetros, estado, formato y página. Controlar los filtros, los límites de volumen y los errores reenviados sin exponer secretos en los periódicos.

Errores de interpretación

Una respuesta exitosa puede contener sólo una página de resultados. Repetir la solicitud más tarde puede proporcionar un estado diferente si los datos han cambiado.

Documento de trabajo que conservar

El diario de recopilación combina solicitud, fecha, respuesta conservada, cobertura y límite. Determina cómo recuperar o comprobar la extracción.