Archivos de datos y APIs

Truco

Did you arrive at this page looking to download OCDS data? Check out the OCP Data Registry.

Diferentes usuarios tienen diferentes necesidades cuando se trata de acceder a datos OCDS. Una necesidad común es la de automatizar la descarga de todos los datos OCDS, de alguna forma.

Las Prácticas recomendadas de datos en la web del W3C describen formas de aumentar la cantidad de usuarios, herramientas y aplicaciones que pueden acceder y hacer un uso efectivo de un determinado conjunto de datos.

Con respecto a tu publicacion OCDS, qué mejores prácticas son más las importantes dependerá de las necesidades particulares de tus usuarios, pero se recomienda considerar:

Para cumplir con los criterios básicos para la calidad de los datos, un usuario debería poder automatizar la descarga de todos los datos, ya sea utilizando una página HTML que lista las URLs de descargas masiva, o utilizando solo datos legibles por máquina como entrada.

Descargas masivas

El paquete de entrega y el paquete de registro pueden proporcionar acceso masivo a entregas y registros, respectivamente.

Sin embargo, archivos muy grandes pueden ser difíciles de descargar y procesar por los usuarios. La siguiente sección sugiere buenas prácticas para ayudar a los usuarios a acceder a los datos. Estos no son requisitos del estándar, pero se basan en experiencias para maximizar la cantidad de usuarios que pueden trabajar con conjuntos de datos con su hardware y software existente.

Límites de tamaño de archivos

Cuando se generan paquetes para descarga masiva, se aplican los siguientes límites:

  • Los paquetes OCDS descomprimidos no deben exceder 1 Gb cada uno.

  • Los paquetes OCDS comprimidos no deben exceder los 10 Mb cada uno.

  • Un mismo paquete OCDS debe contener un máximo de 250.000 adjudicaciones o contratos.

Cuando es probable que un archivo exceda estos límites, las entregas o registros deben de dividirse en múltiples documentos. Las descargas masivas que se generan dinámicamente no están obligados a aplicar estos límites, aunque los publicadores deben considerar guiar a los usuarios cuando una consulta puede generar un archivo muy grande.

Segmentación de archivos

Cuando los límites sugeridos comprenden la publicación de muchos archivos, los publicadores deben considerar la manera de dividir los datos en múltiples archivos.

Para entregas, los publicadores pueden:

  1. Segmentar por fecha de entrega- poniendo todas las entregas que salieron en un mismo día, mes o año en el mismo archivo;

  2. Segmentar por identificador de proceso de contrataciones- poniendo todas las entregas relacionadas a un conjunto de identificadores de proceso de contrataciones en el mismo paquete;

Para registros, los publicadores pueden segmentar por la primera fecha de entrega asociada con un proceso de contrataciones, o por identificador de proceso de contrataciones.

Seguir estos enfoques evitará que las entregas y los registros "salten" entre archivos cuando se actualicen los archivos masivos.

Compresión

Los paquetes OCDS pueden comprimirse para ahorrar en espacio de disco y en ancho de banda.

Cuando comprima paquetes, use ZIP o GZIP, ya que estos están comúnmente disponibles, a menudo sin software adicional. Evite RAR, que requiere software adicional.

Servir archivos

El servidor web que proporciona acceso a archivos masivos debe informar el encabezado HTTP Last-Modified correctamente, para que las aplicaciones que consumen los datos solo necesiten descargar archivos actualizados.

Además, los publicadores deben asegurarse de que la exportación de datos se complete con éxito, es decir, que no se trunca ningún archivo.

Entregas y registros individuales

Cada entrega y registro debe poder ser accedido mediante una URL permanente. Esto se puede lograr mediante:

  • Archivando un paquete de entrega de "entrega-única" para cada entrega en un sistema de archivos accesible desde la web a medida que se crea, y luego fusionando regularmente estas entregas en registros en el mismo sistema de archivos. Un enfoque podría ser tener un directorio para cada ocid y colocar las entregas y el registro relacionado con ese proceso en ese directorio.

  • Proporcionar acceso a cada entrega y los registros fusionados a través de una API.

Los editores deben considerar cómo garantizar que las URL se mantengan estables, incluso cuando se produce un cambio de sistemas.

Acceso a la API

El diseño de una API es un tema extenso. Como tal, la siguiente guía no pretende ser exhaustiva ni prescriptiva. Siempre que sea posible, los publicadores deben realizar su propia investigación de usuarios.

Visibilidad

Asegúrese de que los endpoints y la documentación de la API sean descubribles. Por ejemplo, agregue un enlace al pie de página de su portal de contrataciones y enumere los endpoints de la API en su portal de datos abiertos.

Documentación

Proporcione la documentación de la API, con al menos las listas de endpoints, métodos y parámetros. Muchos publicadores usan Swagger para documentar sus API.

Control de acceso y limitación de velocidad

Evite agregar controles de acceso (como registro de usuarios o API keys), para maximizar la facilidad de acceso a la publicación.

Si los controles de acceso son necesarios, no utilice tokens de acceso que deban actualizarse regularmente. Por ejemplo, cada dos horas es demasiado frecuente.

Si la API implementa límites de velocidad (throttling):

Completitud

Asegúrese de que se pueda acceder a todos los datos de OCDS a través de la API. Por ejemplo, si la fuente de datos es un índice de Elasticsearch, implemente la paginación mediante search_after, o asegúrese de que index.max_result_window sea suficientemente grande para devolver todos los resultados.

Endpoints

Sus opciones de diseño en esta área deben estar informadas por investigaciones de usuario. Dicho esto, puede considerar proporcionar:

  • Un endpoint de paquete de entregas con paginación, para obtener múltiples entregas sin proporcionar un OCID e ID de entrega específicos

  • Un endpoint de paquete de registros con paginación, para obtener múltiples registros sin proporcionar un OCID específico

  • Un endpoint de entrega, para obtener una entrega individual por OCID y ID de entrega

  • Un endpoint de registro, para obtener un registro individual por OCID

Para los endpoints de paquete, también puedes proveer opciones de filtros y ordenamiento. En particular, considera filtros de fecha y/o una opción de ordenamiento en orden cronológico inverso, para que los usuarios puedan obtener solamente datos nuevos o actualizados.

Si escoges proveer endpoints para obtener registros y/o entregas individuales pero no endpoints para paginar a través de registros y/o entregas, entonces necesitas proveer una lista legible por máquina de los OCIDs y/o IDs de las entregas. De lo contrario, no será posible automatizar la descarga de todos los datos, lo cual es un criterio básico de calidad de los datos.

Formato de respuesta

  • Coloque la entrega, el registro o el paquete en el nivel superior de los datos JSON. Por ejemplo, no lo incruste en un array de resultados.

  • Use una biblioteca JSON en lugar de implementar la serialización JSON usted mismo. Esto también garantiza que la codificación sea UTF-8.

  • Elimine los caracteres NULL (\u0000) de la respuesta JSON. Los usuarios no pueden importar estos caracteres a algunas bases de datos SQL.

  • Si no se pueden devolver resultados, utilice un código de error HTTP adecuado (400-599); no devuelva un objeto JSON con un mensaje de error y un código de estado HTTP 200. Dicho esto, si una solicitud de búsqueda no arroja resultados, es apropiado usar un código de estado HTTP 200, con un conjunto de resultados vacío.

Paginación

Para soportar la paginación, el objeto links de nivel superior en los paquetes de entrega y los paquetes de registro tiene dos campos:

  • next: Una URL al siguiente paquete sequencial

  • prev: Una URL al paquete sequencial anterior

Asegúrese de que el rendimiento de la API no se degrade en páginas avanzadas. Por ejemplo, si la fuente de datos es una base de datos SQL, utilice el método seek (también conocido como paginación de conjunto de claves) en lugar de una cláusula OFFSET.

Al usar el método seek, puede usar cualquiera de estos parámetros del tipo query string para construir las URL next y/o prev:

  • cursor=CURSOR, para devolver una página de resultados posicionada después del cursor, en orden secuencial. El cursor puede ser un ID de fila o similar.

  • since=TIMESTAMP, para devolver una página de resultados que se modifican después de la marca de tiempo since, en orden cronológico.

Al usar el método offset, puede usar cualquiera de estos parámetros del tipo query string para construir las URL next y/o prev:

  • offset=NUMBER, para devolver una página de resultados que se colocan después del número de offset, en orden secuencial. Utilice offset=0 para el primer desplazamiento.

  • page=NUMBER, para devolver una página de resultados que están posicionados en el número de page, en orden secuencial. Usa page=1 para la primera página, no page=0.

En cualquier caso:

  • Utilice limit=NUMBER para limitar el número de resultados devueltos en cada página.

  • Incluya el número total de resultados en todas las páginas.

In addition to performance reasons, the seek method is preferred to the offset method when results are ordered in reverse chronology, because, with the offset method:

  • Una página determinada no devolverá los mismos resultados con el tiempo. page=1 devolverá resultados diferentes hoy, la próxima semana y el próximo año.

  • Los usuarios pueden recibir resultados duplicados mientras paginan. Por ejemplo, si se publica una nueva entrega en la página 1 mientras los usuarios están paginando, el resultado en la parte inferior de cada página se moverá a la parte superior de la página siguiente.

  • Es más difícil para los usuarios sincronizar con la API. Con el método seek, los usuarios pueden obtener nuevos resultados al enviar la marca de tiempo o el ID de su última solicitud. Con page, los usuarios deben determinar qué resultados son nuevos o antiguos.

Monitoreo

Configure el monitoreo de errores, de modo que si una solicitud provoca un error interno del servidor HTTP 500, pueda investigar.

CSV y serializaciones de hojas de cálculo

La página serialización proporciona detalles sobre cómo generar versiones 'flat' de datos OCDS para su uso en un software de hoja de cálculo.

Los mismos principios que se discutieron anteriormente sobre archivos masivos deben aplicarse a descargas CSV o Excel de los datos.