Serviços Unificados goszakup.gov.kz - Versão 2

Trabalho como desenvolvedor na empresa Center for Electronic Finance JSC.
Um de nossos projetos é o Portal de Compras Públicas da República do Cazaquistão - goszakup.gov.kz.

Há um ano, lançamos um grande projeto - Serviços Unificados (OpenData).
Para implementação, foi utilizada a metodologia RestAPI.

Hoje vou falar sobre a nova versão de nossos serviços e a nova interface para trabalhar com eles.



Desenvolvemos e lançamos 6 serviços de dados abertos:

• Registro de participantes
• Registro de fornecedores inescrupulosos
• Registro de planos anuais
• Anúncios de estado. aquisição
• Lot Register
• Registro de contratos

Muitas empresas no Cazaquistão já estão conectando e recebendo dados sobre esses serviços.
O lançamento do Open Data nos permitiu reduzir a carga do banco de dados em cerca de 40%, devido ao fato de as empresas não precisarem escrever analisadores diferentes para coletar dados sobre Compras Públicas. É o suficiente para passar por uma missão difícil :)

1. escreva uma solicitação para um token de acesso
2. leia a documentação dos serviços em nosso portal goszakup.gov.kz/ru/developer/ows
3. escreva seu cliente RestAPI

Serviços Unificados - Uma Nova Abordagem

O RestAPI torna possível obter dados de forma mais conveniente e rápida do que analisar um site, mas o RestAPI padrão não oferece às empresas flexibilidade e para criar uma conexão com objetos, você precisa obter todos os dados primeiro e somente depois criar os links entre eles.
Para receber dados em um anúncio, é necessário que o RestAPI solicite primeiro o registro de anúncios, depois o registro de lotes e, finalmente, o registro de planos. Isso significa que, para receber um comunicado, é necessário concluir pelo menos 3 solicitações e, se você precisar receber dados em 50 anúncios, precisará de pelo menos 101 solicitações para RestAPI, desde que cada anúncio tenha 1 lote (1 para 50 anúncios, 50 para lotes, 50 para recebimento de pontos do plano).

Encontramos uma maneira de reduzir esse valor a uma solicitação!

Estamos lançando a segunda versão do Unified Services - ows.goszakup.gov.kz/v2 .
Além de expandir os conjuntos de dados, estamos expandindo a capacidade de trabalhar com nossa API.

Agora os dados podem ser obtidos via RestAPI e a nova interface - GraphQL.
ows.goszakup.gov.kz/v2/graphql



Não descreverei o que é o GraphQL; para isso, você pode ler o artigo aliksend - O que é este GraphQL?

Vou lhe dizer quais vantagens tivemos após iniciar o GraphQL:

• Solicitar flexibilidade;
• Obtendo objetos relacionados;
• Digitação completa de solicitações e respostas;
• Nova interface de pesquisa de dados.

Solicitar flexibilidade

Com uma solicitação RestAPI simples, você obtém o formato de dados previamente estabelecido.
Ao consultar o GraphQL, você obtém os dados no formato necessário.

Ao solicitar dados, você mesmo determina o formato dos dados necessários, por exemplo, o ID e

Número do contrato

{ contract { id contract_number_sys } } 

Em resposta, obtemos apenas esses dados:

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

Bem, essas consultas são as mais fáceis de implementar o GraphQL. As empresas têm a oportunidade de escolher quais dados desejam receber, enquanto não precisamos fazer ajustes como se estivessem trabalhando com o RestAPI. Você obtém apenas o conjunto de campos necessário.

Recuperando objetos relacionados

Não paramos de repetir a funcionalidade do RestAPI simplesmente possibilitando a seleção parcial de dados.

Implementamos o segundo recurso do GraphQL - relacionamento com objetos.

Se você receber dados de acordo com a RestAPI, para receber dados sobre o contrato e a empresa, o cliente no contrato precisaria primeiro obter dados do Registro de Participantes e somente então receber dados do Registro de Contratos e construir a conexão entre os próprios objetos.

Agora, ao trabalhar com o GraphQL, você não precisa receber totalmente os dados do Registro do participante, basta solicitar dados no formato em que está interessado:

 { contract { id contract_number_sys customer { name_ru } } } 

Assim, com uma solicitação, obtemos os dados do contrato e da empresa do cliente:

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

E existem muitas dessas relações que foram implementadas; agora as empresas para receber dados exigirão significativamente menos solicitações de dados. Ao mesmo tempo, não é mais necessário adivinhar exatamente como os objetos estão relacionados entre si, para receber conjuntos de dados completos para conectá-los.

Tentei demonstrar parcialmente a estrutura de conexão que consegui alcançar.

Digitando solicitações e respostas

Muitos defensores das solicitações SOAP sempre colocam a mais importante digitação de dados positivos.
O RestAPI, diferentemente do SOAP, não possui uma descrição de sua estrutura e você não sabe de antemão que tipo de dados. Mas o GraphQL muda tudo.

Agora você pode solicitar dados do GraphQL em todo o esquema de dados e receberá:

• Descrição completa da estrutura de dados;
• Descrição de qual campo possui um tipo de dados (Int, String, Boolean);
• Descrição de objetos aninhados e estrutura de campo de objetos aninhados;
• Descrição detalhada, por exemplo, em russo para cada campo;
• Receba uma notificação de que algum campo recebeu o sinalizador Descontinuado com uma descrição.

Eu uso o programa Insomnia REST Client - insomnia.rest para trabalhar com o GraphQL
Ao trabalhar com o GraphQL, ele recebe toda a estrutura de objetos e solicita ao construir uma consulta.

Vou dar algumas capturas de tela como exemplo.

1. Ajuda na construção de consultas desde o programa recebeu uma estrutura completa de objetos



2. Dica para a descrição de cada campo com seu tipo de dados e descrição



3. Dica se algum campo recebeu uma bandeira - Descontinuado



E esse recurso do GraphQL permite que você tenha uma imagem completa de quais campos e objetos você trabalha.

Nova interface de recuperação de dados

E eu deixei o mais interessante no final.

Tudo parece legal, é possível construir sua própria estrutura de dados, existe uma conexão com outros objetos, todos os dados são digitados. Mas ainda falta alguma coisa ...

Não há oportunidade suficiente para pesquisar nesses dados.

Desde o início, um formato de pesquisa foi implementado com os parâmetros na própria solicitação:

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

Mas aqui eu tive vários problemas:

1. com um grande número de critérios de pesquisa, a consulta se torna simplesmente ilegível;
2. é impossível determinar a matriz ao pesquisar dados para pesquisar diversas variantes do mesmo campo.

Para simplificar a construção de consultas e expandir a capacidade de pesquisa, implementei objetos aninhados para filtrar dados.

Definimos uma variável na solicitação indicando o objeto de filtragem.

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

Nós descrevemos os próprios parâmetros de pesquisa de dados:

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

E, como resultado, receberemos todos os anúncios com os status 1 e 2.

Na própria solicitação, indicamos apenas a estrutura de dados e todos os parâmetros de pesquisa entram na transmissão de parâmetros, onde já podemos transferir matrizes de dados para filtragem de acordo com vários critérios.



Além disso, no próprio esquema do GraphQL, todos nós também temos uma descrição desse objeto de pesquisa:

Serviços Unificados - Versão 2.0:

Serviços de trabalho:

• Registro de participantes
• Registro de anúncios
• Registro de contratos
• Registro de atos
• Lot Register
• Registro de planos anuais
• Registro de fornecedores inescrupulosos

Lançamos uma nova funcionalidade que simplifica bastante o trabalho com nossa API, possui uma estrutura de consulta flexível e a capacidade de pesquisar dados de acordo com os critérios especificados.

Não perdemos a velocidade de obtenção de dados, mas reduzimos apenas por isso o número de solicitações necessárias para obter dados.

Pudemos avisar no esquema de dados sobre campos desabilitados ou renomeados.

Planejamos desenvolver ainda mais a API e permitir a pesquisa morfológica de dados sobre serviços.