{"id":34354,"date":"2019-10-31T21:57:51","date_gmt":"2019-10-31T18:57:51","guid":{"rendered":"https:\/\/prohoster.info\/blog\/pisali-api-porvali-xml-dva\/"},"modified":"2019-10-31T21:57:51","modified_gmt":"2019-10-31T18:57:51","slug":"pisali-api-porvali-xml-dva","status":"publish","type":"post","link":"https:\/\/prohoster.info\/pt\/blog\/administrirovanie\/pisali-api-porvali-xml-dva","title":{"rendered":"Escrevemos API \u2014 rompemos XML (dois)","gt_translate_keys":[{"key":"rendered","format":"text"}]},"content":{"rendered":"

A primeira API do MeuArmaz\u00e9m surgiu h\u00e1 10 anos. Durante todo esse tempo, temos trabalhado nas vers\u00f5es existentes da API e desenvolvido novas. E j\u00e1 enterramos v\u00e1rias vers\u00f5es da API. <\/p>\n

Este artigo trar\u00e1 muitos t\u00f3picos: como criamos a API, por que ela \u00e9 necess\u00e1ria para um servi\u00e7o em nuvem, o que oferece aos usu\u00e1rios, em quais armadilhas j\u00e1 ca\u00edmos e o que queremos fazer a seguir.
\n<\/a><\/noindex>
\nMeu nome \u00e9 Oleg Alexeev oalexeev<\/a><\/noindex>, sou diretor t\u00e9cnico e cofundador do MeuArmaz\u00e9m. <\/p>\n

Por que criar uma API para o servi\u00e7o<\/h2>\n

\nNossos clientes, que somam dezenas de milhares de empreendedores, utilizam ativamente solu\u00e7\u00f5es em nuvem: servi\u00e7os banc\u00e1rios, lojas online, controle de invent\u00e1rio, CRM. Ap\u00f3s conectar-se a um, \u00e9 dif\u00edcil parar. E assim, o quinto, oitavo, d\u00e9cimo servi\u00e7o facilita o trabalho do empreendedor, mas os dados entre esses servi\u00e7os em nuvem t\u00eam que ser transferidos manualmente. O trabalho se torna um pesadelo.<\/p>\n

A solu\u00e7\u00e3o \u00f3bvia \u00e9 dar aos usu\u00e1rios a possibilidade de transferir dados entre servi\u00e7os em nuvem. Por exemplo, importar e exportar dados como arquivos que podem ser carregados no servi\u00e7o desejado. Os arquivos geralmente precisam ser adaptados ao formato de cada servi\u00e7o. Isso \u00e9 um trabalho manual relativamente simples, mas, com o aumento do n\u00famero desses servi\u00e7os, torna-se cada vez mais complicado realiz\u00e1-lo.<\/p>\n

Portanto, o pr\u00f3ximo passo \u00e9 a API. Com ela, o servi\u00e7o em nuvem se beneficia ao conectar v\u00e1rios servi\u00e7os em um \u00fanico ponto. O surgimento de um ecossistema assim atrai novos clientes, oferecendo possibilidades adicionais. Um produto com novas funcionalidades torna-se mais rent\u00e1vel e \u00fatil.<\/p>\n

Se voc\u00ea criar suas pr\u00f3prias interfaces de programa\u00e7\u00e3o, isso atrai vendedores externos na forma de programadores que conhecem seu produto gra\u00e7as \u00e0 API. Eles come\u00e7am a construir solu\u00e7\u00f5es com base na API oferecida e ganham dinheiro automatizando as tarefas de seus clientes.<\/p>\n

O sistema de contabilidade do MeuArmaz\u00e9m \u00e9 constru\u00eddo sobre processos simples. O principal \u00e9 trabalhar com documentos prim\u00e1rios, permitir receber e despachar mercadorias, e gerar relat\u00f3rios de neg\u00f3cios com base nesses documentos. Tamb\u00e9m h\u00e1 transfer\u00eancia de dados, por exemplo, para contabilidade em nuvem, e recebimento de informa\u00e7\u00f5es de sistemas banc\u00e1rios ou pontos de venda. Al\u00e9m disso, trabalhamos com lojas online: obtemos informa\u00e7\u00f5es sobre produtos e enviamos dados sobre estoques.<\/p>\n

\"Escrevemos
\n<\/p>\n

Primeiro API do MeuArmaz\u00e9m<\/h2>\n

\nAo longo de 10 anos trabalhando com o API do MeuArmaz\u00e9m, desenvolvemos diversas integra\u00e7\u00f5es que permitem a troca de dados, intera\u00e7\u00e3o com bancos, processamento de pagamentos e uso de telefonia externa.<\/p>\n

No primeiro ano, tornamos poss\u00edvel exportar quaisquer dados no formato XML. Naquela \u00e9poca, os usu\u00e1rios entendiam melhor e preferiam manter os dados offline, ao inv\u00e9s de em alguma nuvem, e por isso oferecemos essa op\u00e7\u00e3o. A exporta\u00e7\u00e3o era iniciada manualmente pelo interface. Assim, n\u00e3o pod\u00edamos ainda cham\u00e1-lo de API. <\/p>\n

Foi tamb\u00e9m nesse per\u00edodo que come\u00e7amos a colaborar com a empresa Rusagro \u2014 eles j\u00e1 utilizavam um ERP \u2018maduro\u2019 para planejamento de produ\u00e7\u00e3o e distribui\u00e7\u00e3o, mas a carga dos vag\u00f5es nas f\u00e1bricas foi automatizada no MeuArmaz\u00e9m. Assim, surgiram as primeiras sementes de uma verdadeira API: a troca entre nosso servi\u00e7o e o ERP era feita pela transmiss\u00e3o de um grande arquivo com dados de todos os tipos de documentos. <\/p>\n

Essa \u00e9 uma boa op\u00e7\u00e3o para troca em lote de dados, mas junto com os documentos era necess\u00e1rio enviar suas depend\u00eancias: informa\u00e7\u00f5es sobre produtos, contrapartes e armaz\u00e9ns. Essa bagun\u00e7a \u00e9 f\u00e1cil de gerar na exporta\u00e7\u00e3o, mas bastante dif\u00edcil de lidar na importa\u00e7\u00e3o, uma vez que em um \u00fanico pacote chegam todas as informa\u00e7\u00f5es: tanto sobre novos documentos quanto sobre os j\u00e1 existentes.<\/p>\n

O primeiro API XML n\u00e3o sobreviveu por muito tempo \u2014 dois anos depois, come\u00e7amos sua reestrutura\u00e7\u00e3o. Desde o in\u00edcio de sua opera\u00e7\u00e3o, cometemos alguns erros na constru\u00e7\u00e3o da interface program\u00e1tica.<\/p>\n

\"Escrevemos
\nComo foi feito o API XML: ilustra\u00e7\u00e3o de um dos nossos arquitetos. Ali\u00e1s, fiquem atentos aos artigos dele.<\/i><\/p>\n

Aqui est\u00e3o nossos principais erros:<\/p>\n

    \n
  1. A marca\u00e7\u00e3o JAXB foi feita diretamente nos beans de entidade. Para comunica\u00e7\u00e3o com o banco de dados, usamos Hibernate, e a mesma marca\u00e7\u00e3o JAXB foi aplicada a esses beans. Esse erro se manifestou quase imediatamente: qualquer atualiza\u00e7\u00e3o na estrutura de dados exigia uma notifica\u00e7\u00e3o urgente a todos que utilizavam a API, ou a constru\u00e7\u00e3o de gambiarras que garantissem a compatibilidade com a estrutura de dados anterior.<\/li>\n
  2. A API surgiu como um complemento e, inicialmente, n\u00e3o definimos qual parte do produto ela formava. N\u00e3o pensamos tamb\u00e9m se a API era algo importante ou se era necess\u00e1rio manter a compatibilidade retroativa para os seus primeiros clientes. Em certo momento, o n\u00famero de usu\u00e1rios da API representou cerca de 5% do pequeno total, e n\u00e3o recebemos aten\u00e7\u00e3o. A filtragem universal feita na \u00e9poca levou a que nos usassem como backend. Essa filtragem n\u00e3o era exatamente GraphQL, mas algo parecido \u2014 funcionava atrav\u00e9s de in\u00fameros par\u00e2metros na string de consulta. Com uma ferramenta t\u00e3o poderosa, os usu\u00e1rios acharam dif\u00edcil resistir, e as solicita\u00e7\u00f5es come\u00e7aram a ser enviadas diretamente do UI de suas lojas online. A situa\u00e7\u00e3o se tornou uma desagrad\u00e1vel surpresa, pois fornecer tal servi\u00e7o deveria exigir uma tarifa\u00e7\u00e3o diferente e, de modo geral, uma compreens\u00e3o diferente da pr\u00f3pria API como produto.<\/li>\n
  3. Devido ao fato de que a API n\u00e3o se desenvolveu como um produto principal, a documenta\u00e7\u00e3o da API foi criada e publicada por um processo secund\u00e1rio \u2014 atrav\u00e9s de engenharia reversa. Esse caminho parece bastante simples e conveniente, mas contradiz o trabalho baseado em contrato. Isso \u00e9 quando existe um componente com um esquema de trabalho pr\u00e9-estabelecido. O desenvolvedor o realiza de acordo com esse esquema e tarefa, o componente \u00e9 testado, e o cliente recebe um produto que corresponde \u00e0 ideia do analista. J\u00e1 a engenharia reversa joga no mercado um produto que simplesmente existe: com gambiarras, solu\u00e7\u00f5es estranhas e bicicletas no lugar da funcionalidade necess\u00e1ria. <\/li>\n
  4. Todo o fluxo de solicita\u00e7\u00f5es que chegava pela API s\u00f3 podia ser analisado como um log do Nginx ou do servidor de aplica\u00e7\u00e3o. Isso n\u00e3o permitiu identificar \u00e1reas tem\u00e1ticas, exceto para segmentar por usu\u00e1rios e assinantes. Se n\u00e3o h\u00e1 como regular o registro de aplicativos ou clientes, torna-se imposs\u00edvel analisar a situa\u00e7\u00e3o. Esse problema afetou o desenvolvimento da API em menor grau, ele est\u00e1 mais relacionado \u00e0 compreens\u00e3o da sua demanda e ao preenchimento de funcionalidades.<\/li>\n<\/ol>\n

    <\/p>\n

    Tentativa n\u00famero dois: REST API<\/h2>\n

    \nEm 2010, tentamos construir um sistema de troca com a contabilidade online - BukhSoft. N\u00e3o decolou. No entanto, durante o processo de integra\u00e7\u00e3o, surgiu uma API completa: um servi\u00e7o REST de interc\u00e2mbio, onde n\u00e3o havia arbitrariedades como chamadas de opera\u00e7\u00f5es em forma de RPC. Toda a comunica\u00e7\u00e3o com a API foi reduzida ao modo padr\u00e3o para REST: na string de requisi\u00e7\u00e3o, cont\u00e9m-se o nome da entidade, e a opera\u00e7\u00e3o realizada com ela \u00e9 definida atrav\u00e9s do m\u00e9todo HTTP. Adicionamos filtragem com base no momento da atualiza\u00e7\u00e3o das entidades, permitindo aos usu\u00e1rios construir replica\u00e7\u00f5es com seus sistemas.<\/p>\n

    No mesmo ano, foi lan\u00e7ada a API para exportar saldos de estoque e produtos. As partes mais valiosas do sistema tornaram-se dispon\u00edveis para os usu\u00e1rios atrav\u00e9s da API - a troca de documentos prim\u00e1rios e dados de c\u00e1lculos sobre saldos e custo dos produtos.<\/p>\n

    Em dezembro de 2015, a RetailCRM publicou a primeira biblioteca de terceiros para acesso \u00e0 nossa API. Ela passou a ser utilizada de forma bastante ativa, e a popularidade do servi\u00e7o, como um todo, cresceu, com a carga na API aumentando mais rapidamente do que no interface web. Em um certo momento, o crescimento se transformou em um salto na carga. <\/p>\n

    \"Escrevemos
    \n
    \n\"Escrevemos
    \n
    \nE esse salto, indicado pela seta \u00e0 esquerda, deixou o servidor que atende nossa API completamente perplexo. Passamos uma semana tentando entender o que exatamente estava gerando essa carga. Descobrimos que eram aquelas mesmas requisi\u00e7\u00f5es, transmitidas para nossa API a partir das frentes dos clientes. Cerca de 50 clientes geraram tudo isso. Foi ent\u00e3o que percebemos um de nossos erros - a completa aus\u00eancia de limites. <\/p>\n

    Como resultado, introduzimos um limite no n\u00famero de requisi\u00e7\u00f5es simult\u00e2neas. De uma conta, agora era poss\u00edvel abrir no m\u00e1ximo duas requisi\u00e7\u00f5es ao mesmo tempo. Isso \u00e9 suficiente para trabalhar em modo de replica\u00e7\u00e3o para troca de dados em modo em lote. E aqueles que queriam nos utilizar como backend foram for\u00e7ados a se adaptar mais aos planos, uma vez que introduzimos em suas ferramentas de software o trabalho com v\u00e1rias contas.<\/p>\n

    Organizando<\/h2>\n

    \nDesde 2014, a demanda pela API existente tornou-se uma parte importante do neg\u00f3cio, e a pr\u00f3pria API gerava o maior volume de dados na troca de informa\u00e7\u00f5es com os clientes. Em 2015, iniciamos o projeto de organiza\u00e7\u00e3o da API. Escolhemos o formato JSON em vez de XML e come\u00e7amos a constru\u00ed-lo com base nas particularidades que identificamos ao implementar a vers\u00e3o anterior:<\/p>\n

      \n
    1. Capacidade de gerenciar vers\u00f5es. A vers\u00e3o permite desenvolver uma nova vers\u00e3o sem afetar o aplicativo existente e sem interromper o funcionamento dos usu\u00e1rios. <\/li>\n
    2. Capacidade do usu\u00e1rio de visualizar os metadados na pr\u00f3pria resposta que recebe.<\/li>\n
    3. Capacidade de compartilhar grandes documentos. Quando processamos um documento com mais de 4-5 mil itens, isso se torna um problema para o servidor: transa\u00e7\u00f5es longas, solicita\u00e7\u00f5es HTTP longas. Desenvolvemos um mecanismo especial que permite atualizar o documento em partes e gerenciar itens individuais desse documento, enviando-os para o servidor.<\/li>\n
    4. Ferramentas para replica\u00e7\u00e3o \u2014 j\u00e1 existiam na vers\u00e3o anterior.<\/li>\n
    5. Limites de carga \u2014 como legado dos erros cometidos na vers\u00e3o anterior. Introduzimos limites na quantidade de solicita\u00e7\u00f5es em um intervalo de tempo, na quantidade de solicita\u00e7\u00f5es simult\u00e2neas e nas solicita\u00e7\u00f5es de um \u00fanico endere\u00e7o IP.<\/li>\n<\/ol>\n

      \nDesde ent\u00e3o, lan\u00e7amos duas vers\u00f5es menores da API e iniciamos v\u00e1rias APIs especializadas, mas de forma geral a abordagem permaneceu inalterada. O formato de troca atualizado e a nova arquitetura permitiram corrigir falhas na API muito mais rapidamente.<\/p>\n

      API do Meu Estoque hoje<\/h2>\n

      \nHoje, a API do Meu Estoque resolve muitas tarefas:<\/p>\n