Services unifiés goszakup.gov.kz - Version 2

Je travaille en tant que développeur au sein de la société Center for Electronic Finance JSC.
L'un de nos projets est le Portail des marchés publics de la République du Kazakhstan - goszakup.gov.kz.

Il y a un an, nous avons lancé un grand projet - Unified Services (OpenData).
Pour la mise en œuvre, la méthodologie RestAPI a été utilisée.

Aujourd'hui, je vais parler de la nouvelle version de nos services et de la nouvelle interface pour travailler avec eux.



Nous avons développé et lancé 6 services Open Data:

• Registre des participants
• Registre des fournisseurs sans scrupules
• Registre des plans annuels
• Annonces d'État. approvisionnement
• Registre des lots
• Registre des contrats

De nombreuses entreprises au Kazakhstan se connectent et reçoivent déjà des données sur ces services.
Le lancement d'Open Data nous a permis de réduire la charge de la base de données d'environ 40% du fait que les entreprises n'ont pas besoin d'écrire différents analyseurs pour collecter des données sur les marchés publics. Il suffit de passer par une quête difficile :)

1. écrire une demande de jeton d'accès
2. lire la documentation des services sur notre portail goszakup.gov.kz/ru/developer/ows
3. écrire votre client RestAPI

Services unifiés - une nouvelle approche

RestAPI permet d'obtenir des données plus facilement et plus rapidement que l'analyse d'un site, mais le RestAPI standard ne donne pas de flexibilité aux entreprises et pour établir une connexion avec des objets, vous devez d'abord obtenir toutes les données et ensuite seulement créer les liens entre eux.
Pour recevoir des données sur une annonce, il est nécessaire par RestAPI de demander d'abord le registre des annonces, puis le registre des lots et enfin le registre des plans. Cela signifie que pour recevoir une annonce, il est nécessaire de remplir au moins 3 demandes, et si vous avez besoin de recevoir des données sur 50 annonces, vous aurez besoin d'au moins 101 demandes à RestAPI, à condition que chaque annonce contienne 1 lot (1 pour recevoir 50 annonces, 50 pour recevoir des lots, 50 à réception des points du plan).

Nous avons trouvé un moyen de réduire ce montant à une seule demande!

Nous lançons la 2e version des services unifiés - ows.goszakup.gov.kz/v2 .
En plus d'étendre les ensembles de données, nous élargissons la capacité de travailler avec notre API.

Maintenant, les données peuvent être obtenues via RestAPI et la nouvelle interface - GraphQL.
ows.goszakup.gov.kz/v2/graphql



Je ne décrirai pas ce qu'est GraphQL, pour cela vous pouvez lire l'article d' aliksend - Qu'est-ce que GraphQL?

Je vais vous dire quels avantages nous avons obtenus après le démarrage de GraphQL:

• Demander de la flexibilité;
• Obtenir des objets associés;
• Dactylographie complète des demandes et des réponses;
• Nouvelle interface de recherche de données.

Demander de la flexibilité

Avec une simple demande RestAPI, vous obtenez le format de données qui a été défini à l'avance.
Lorsque vous interrogez GraphQL, vous obtenez les données au format dont vous avez besoin.

Lorsque vous demandez des données, vous déterminez vous-même le format des données dont vous avez besoin, par exemple l'ID et

Numéro de contrat

{ contract { id contract_number_sys } } 

En réponse, nous obtenons uniquement ces données:

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

Eh bien, ces requêtes sont les plus faciles à implémenter GraphQL. Les entreprises ont la possibilité de choisir les données qu'elles souhaitent recevoir, alors que nous n'avons pas besoin de faire des ajustements comme si c'était le cas avec RestAPI. Vous obtenez uniquement l'ensemble des champs nécessaires.

Récupération des objets associés

Nous ne nous sommes pas contentés de répéter les fonctionnalités de RestAPI simplement en permettant de sélectionner partiellement des données.

Nous avons implémenté la 2ème fonctionnalité de GraphQL - relations d'objets.

Si vous recevez des données selon RestAPI, afin de recevoir des données sur le contrat et sur l'entreprise, le client dans le contrat devra d'abord obtenir des données du registre des participants , puis seulement recevoir des données du registre des contrats et établir la connexion entre les objets eux-mêmes.

Désormais, lorsque vous travaillez avec GraphQL, vous n'avez pas besoin de recevoir entièrement les données du Registre des participants, il vous suffit de demander des données au format qui vous intéresse:

 { contract { id contract_number_sys customer { name_ru } } } 

Ainsi, avec une seule demande, nous obtenons à la fois les données du contrat et les données de l'entreprise pour le client:

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

Et de nombreuses relations de ce type ont été mises en place. Désormais, les entreprises qui reçoivent des données auront besoin de beaucoup moins de demandes pour recevoir des données. Dans le même temps, il n'est plus nécessaire de deviner exactement comment les objets sont liés les uns aux autres, pour recevoir des ensembles de données complets afin de les connecter les uns aux autres.

J'ai essayé de démontrer partiellement la structure de connexion que j'ai réussi à atteindre.

Saisir des demandes et des réponses

De nombreux partisans des demandes SOAP ont toujours mis le plus important - le typage des données.
RestAPI, contrairement à SOAP, n'a pas de description de sa structure et vous ne savez pas à l'avance quel type de données. Mais GraphQL change tout.

Vous pouvez maintenant demander des données à GraphQL tout au long du schéma de données et vous recevrez:

• Description complète de la structure des données;
• Description du champ qui a un type de données (Int, String, Boolean);
• Description des objets imbriqués et structure des champs des objets imbriqués;
• Description détaillée, par exemple, en russe pour chaque domaine;
• Recevez une notification indiquant qu'un champ a reçu l'indicateur Obsolète avec une description.

J'utilise le programme Insomnia REST Client - insomnia.rest pour travailler avec GraphQL
Lorsque vous travaillez avec GraphQL, il reçoit la structure entière des objets et des invites lors de la construction d'une requête.

Je vais donner quelques captures d'écran à titre d'exemple.

1. Aide à la création de requêtes depuis le programme a reçu une structure complète d'objets



2. Astuce pour la description de chaque champ avec son type de données et sa description



3. Indication si un champ a reçu un indicateur - Obsolète



Et cette fonctionnalité de GraphQL vous permet d'avoir une image complète des champs et objets avec lesquels vous travaillez.

Nouvelle interface de récupération de données

Et j'ai laissé le plus intéressant au final.

Tout semble cool, il est possible de construire sa propre structure de données, il y a une connexion avec d'autres objets, toutes les données sont tapées. Mais il manque encore quelque chose ...

Il n'y a pas assez de possibilité de rechercher sur ces données.

Dès le début, un format de recherche a été implémenté avec les paramètres dans la requête elle-même:

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

Mais ici, j'ai rencontré un certain nombre de problèmes:

1. avec un grand nombre de critères de recherche, la requête devient tout simplement illisible;
2. il est impossible de déterminer le tableau lors de la recherche de données pour rechercher plusieurs variantes du même champ.

Pour simplifier la construction des requêtes et étendre la capacité de recherche, j'ai implémenté des objets imbriqués pour filtrer les données.

Nous définissons une variable dans la requête indiquant l'objet filtrant.

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

Nous décrivons les paramètres de recherche de données eux-mêmes:

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

Et par conséquent, nous recevrons toutes les annonces ayant les statuts 1 et 2.

Dans la demande elle-même, nous n'indiquons que la structure des données, et tous les paramètres de recherche entrent dans la transmission des paramètres où nous pouvons déjà transférer des tableaux de données pour le filtrage selon plusieurs critères.



De plus, dans le schéma GraphQL lui-même, nous avons également tous une description d'un tel objet de recherche:

Services unifiés - Version 2.0:

Les services fonctionnent:

• Registre des participants
• Registre des annonces
• Registre des contrats
• Registre des actes
• Registre des lots
• Registre des plans annuels
• Registre des fournisseurs sans scrupules

Nous avons lancé une nouvelle fonctionnalité qui simplifie considérablement le travail avec notre API, a une structure de requête flexible et la possibilité de rechercher des données selon des critères spécifiés.

Nous n'avons pas perdu dans la vitesse d'obtention des données, mais ne faisons que réduire de ce fait le nombre de demandes nécessaires pour obtenir les données.

Nous avons pu avertir dans le schéma de données les champs désactivés ou renommés.

Nous prévoyons de développer davantage l'API et de permettre également la recherche morphologique des données sur les services.