Servicios unificados goszakup.gov.kz - Versión 2

Trabajo como desarrollador en la empresa Center for Electronic Finance JSC.
Uno de nuestros proyectos es el Portal de Contratación Pública de la República de Kazajstán: goszakup.gov.kz.

Hace un año, lanzamos un gran proyecto: Servicios Unificados (OpenData).
Para la implementación, se utilizó la metodología RestAPI.

Hoy hablaré sobre la nueva versión de nuestros servicios y la nueva interfaz para trabajar con ellos.



Hemos desarrollado y lanzado 6 servicios de datos abiertos:

• Registro de participantes
• Registro de proveedores sin escrúpulos
• Registro de planes anuales.
• Anuncios de estado. adquisición
• Registro de lote
• Registro de contratos

Muchas empresas en Kazajstán ya están conectando y recibiendo datos sobre estos servicios.
El lanzamiento de Open Data nos permitió reducir la carga de la base de datos en aproximadamente un 40% debido al hecho de que las empresas no necesitan escribir diferentes analizadores para recopilar datos sobre Contratación Pública. Es suficiente pasar por una búsqueda difícil :)

1. escribir una solicitud para un token de acceso
2. lea la documentación de servicios en nuestro portal goszakup.gov.kz/ru/developer/ows
3. escribe tu cliente RestAPI

Servicios unificados: un nuevo enfoque

RestAPI hace posible obtener datos de manera más conveniente y rápida que analizar un sitio, pero el RestAPI estándar no brinda flexibilidad a las empresas y para construir una conexión con objetos, primero debe obtener todos los datos y solo luego crear los enlaces entre ellos.
Para recibir datos en un anuncio, RestAPI necesita solicitar primero el registro de anuncios, luego el registro de lotes y finalmente el registro de planes. Esto significa que para recibir un anuncio, es necesario completar al menos 3 solicitudes, y si necesita recibir datos sobre 50 anuncios, necesitará al menos 101 solicitudes para RestAPI, siempre que cada anuncio tenga 1 lote (1 para recibir 50 anuncios, 50 para recibir lotes, 50 para recibo de puntos del plan).

¡Hemos encontrado una manera de reducir esta cantidad a una sola solicitud!

Estamos lanzando la segunda versión de Unified Services: ows.goszakup.gov.kz/v2 .
Además de expandir los conjuntos de datos, estamos ampliando la capacidad de trabajar con nuestra API.

Ahora los datos se pueden obtener a través de RestAPI y la nueva interfaz: GraphQL.
ows.goszakup.gov.kz/v2/graphql



No describiré qué es GraphQL, para esto puede leer el artículo aliksend : ¿Qué es GraphQL?

Te diré qué ventajas obtuvimos después de iniciar GraphQL:

• Solicitar flexibilidad;
• Obteniendo objetos relacionados;
• Escritura completa de solicitudes y respuestas;
• Nueva interfaz de búsqueda de datos.

Solicitar flexibilidad

Con una simple solicitud RestAPI, obtienes el formato de datos que se estableció por adelantado.
Cuando consulta GraphQL, obtiene los datos en el formato que necesita.

Al solicitar datos, usted mismo determina el formato de los datos que necesita, por ejemplo, la ID y

Número de contrato

{ contract { id contract_number_sys } } 

En respuesta, solo obtenemos estos datos:

 { "data": { "contract": [ { "id": 1, "contract_number_sys": "_" } ] } } 

Bueno, tales consultas son las más fáciles de implementar GraphQL. Las empresas tienen la oportunidad de elegir qué datos desean recibir, mientras que no necesitamos hacer ningún ajuste como si se tratara de trabajar con RestAPI. Solo obtiene el conjunto de campos que se necesita.

Recuperando objetos relacionados

No nos detuvimos en repetir la funcionalidad de RestAPI simplemente haciendo posible seleccionar parcialmente los datos.

Hemos implementado la segunda característica de GraphQL - relaciones de objeto.

Si recibe datos de acuerdo con RestAPI, para recibir datos sobre el contrato y sobre la compañía, el cliente en el contrato primero necesitaría obtener datos del Registro de participantes , y solo luego recibir datos del Registro de contratos y construir la conexión entre los objetos mismos.

Ahora, cuando trabaje con GraphQL, no necesita recibir completamente los datos del Registro de participantes, solo solicite los datos en el formato que le interese:

 { contract { id contract_number_sys customer { name_ru } } } 

Por lo tanto, con una solicitud, obtenemos datos del contrato y de la empresa para el cliente:

 { "data": { "contract": [ { "id": 1, "contract_number_sys": "_", "customer" : { "name_ru": " " } } ] } } 

Y hay muchas relaciones de este tipo que se han implementado, ahora las empresas que recibirán datos requerirán significativamente menos solicitudes para recibir datos. Al mismo tiempo, ya no es necesario adivinar exactamente cómo se relacionan los objetos entre sí, para recibir conjuntos de datos completos para conectarlos entre sí.

Traté de demostrar parcialmente la estructura de conexión que logré lograr.

Escribir solicitudes y respuestas

Muchos defensores de las solicitudes SOAP siempre han puesto la ventaja más importante: la tipificación de datos.
RestAPI, a diferencia de SOAP, no tiene una descripción de su estructura y no sabe de antemano qué tipo de datos. Pero GraphQL lo cambia todo.

Ahora puede solicitar datos de GraphQL en todo el esquema de datos y recibirá:

• Descripción completa de la estructura de datos;
• Descripción de qué campo tiene un tipo de datos (Int, String, Boolean);
• Descripción de objetos anidados y estructura de campo de objetos anidados;
• Descripción detallada, por ejemplo, en ruso para cada campo;
• Reciba una notificación de que algún campo ha recibido el indicador Desaprobado con una descripción.

Uso el programa Insomnia REST Client - insomnia.rest para trabajar con GraphQL
Cuando trabaja con GraphQL, recibe toda la estructura de objetos y avisos al crear una consulta.

Daré algunas capturas de pantalla como ejemplo.

1. Ayuda en la construcción de consultas desde el programa recibió una estructura completa de objetos



2. Sugerencia para la descripción de cada campo con su tipo de datos y descripción



3. Sugerencia si algún campo recibió una bandera: en desuso



Y esta característica de GraphQL le permite tener una imagen completa de los campos y objetos con los que trabaja.

Nueva interfaz de recuperación de datos.

Y dejé lo más interesante al final.

Todo parece estar bien, es posible construir su propia estructura de datos, hay una conexión con otros objetos, todos los datos están escritos. Pero aún falta algo ...

No hay suficientes oportunidades para buscar en estos datos.

Desde el principio, se implementó un formato de búsqueda con los parámetros en la solicitud misma:

 { trd_buy(ref_buy_status_id: 1) { name_kz name_ru } } 

Pero aquí me encontré con una serie de problemas:

1. con una gran cantidad de criterios de búsqueda, la consulta se vuelve simplemente ilegible;
2. Es imposible determinar la matriz cuando se buscan datos para buscar varias variantes del mismo campo.

Para simplificar la construcción de consultas y ampliar la capacidad de búsqueda, implementé objetos anidados para filtrar datos.

Definimos una variable en la solicitud que indica el objeto de filtrado.

 query($filter: TrdBuyFiltersInput){ trd_buy(filters: $filter) { name_kz name_ru } } 

Describimos los propios parámetros de búsqueda de datos:

 { "filter": { "ref_buy_status_id": [1, 2] } } 

Y como resultado, recibiremos todos los anuncios que tengan los estados 1 y 2.

En la solicitud en sí, indicamos solo la estructura de datos, y todos los parámetros de búsqueda entran en la transmisión de parámetros donde ya podemos transferir matrices de datos para filtrar de acuerdo con varios criterios.



Además, en el esquema GraphQL, todos tenemos una descripción de dicho objeto de búsqueda:

Servicios unificados - Versión 2.0:

Servicios de trabajo:

• Registro de participantes
• Registro de anuncios.
• Registro de contratos
• Registro de actos
• Registro de lote
• Registro de planes anuales.
• Registro de proveedores sin escrúpulos

Lanzamos una nueva funcionalidad que simplifica enormemente el trabajo con nuestra API, tiene una estructura de consulta flexible y la capacidad de buscar datos de acuerdo con criterios específicos.

No hemos perdido la velocidad de obtención de datos, sino que solo reducimos debido a esto el número de solicitudes necesarias para obtener datos.

Pudimos advertir en el esquema de datos sobre campos deshabilitados o renombrados.

Planeamos desarrollar aún más la API y permitir la búsqueda morfológica de datos en los servicios también.