Por um ano e meio, integramos a API a vinte serviços externos. As cinco primeiras integrações passaram por dores e lágrimas - cometemos todos os erros possíveis. Eles reescreveram o código várias vezes, se separaram dos parceiros pouco antes do lançamento, porque não podiam concordar com melhorias. Perdeu tempo e dinheiro.
Mas, a cada nova integração, surgíamos soluções para problemas recorrentes. Como resultado, fizemos a última integração quatro vezes mais rápida que a primeira. O que agora fazemos de maneira diferente - leia o artigo.
Para que você possa entender melhor as especificidades de nossas integrações, descreveremos brevemente o que fazemos. Estamos desenvolvendo um corretor online. Princípio do trabalho: o usuário chega ao site, preenche o questionário, o transferimos para as organizações de microfinanças (IMFs) e recebemos aprovação ou recusa deles para um empréstimo. O usuário seleciona uma oferta adequada e recebe dinheiro. Para fazer isso funcionar on-line, nos integramos às IMFs via API.
Avalie a prontidão do parceiro para integração usando uma lista de verificação e especificação
Analisaremos dois cenários: quando um parceiro em potencial já tiver uma API para aceitar aplicativos e quando não. Ambos os cenários sugerem que o parceiro deseja se integrar conosco e está pronto para gastar tempo nisso.
O parceiro não possui API - enviamos a especificação
Anteriormente, explicamos ao parceiro, verbalmente ou em correspondência, o que precisávamos para integração, e o parceiro com base nessas explicações criou uma API para aceitar aplicativos com o Finspin. Não concordamos com os requisitos para modelos, objetos, campos do questionário e as regras para sua validação. Descreveu rapidamente o objetivo dos métodos e as possíveis respostas. O resultado acabou sendo infinitamente longe do esperado, porque nosso entendimento da API era muito diferente do da parceria. Eu tive que refazer tudo.
Agora Nós escrevemos nossa especificação - um arquivo YAML que pode ser aberto no Swagger. Na especificação, descrevemos a API mais adequada para integrar o Finspin às IMFs: campos do questionário e regras para validação, formatos e tipos de solicitações com respostas, nomes de métodos, possíveis erros e status. Registramos o status do estado do aplicativo que planejamos receber, por exemplo: "aceito para processamento", "pontuação em andamento", "empréstimo recusado", "aprovação" etc.
Enviamos a especificação ao parceiro e ele decide se pode fornecer uma API desse tipo. Se não puder, observa pontos problemáticos na especificação, por exemplo, nem todos os estados do aplicativo estão prontos para transferir para a API ou não há campos suficientes no questionário. E já estamos discutindo pontos específicos, não entidades abstratas. O parceiro não perde tempo escrevendo sua documentação, mas ajusta a nossa.
Passamos dois dias criando a especificação, mas agora estamos economizando dezenas de horas em aprovações e melhorias na API. Além disso, com a ajuda das especificações, filtramos rapidamente os parceiros que não estão prontos para a integração. Nos estágios iniciais, fica claro que nossos processos de processamento de aplicativos on-line são muito diferentes: não é rentável a integração.
O parceiro tem uma API - percorra a lista de verificação
Costumávamos obter as especificações de um parceiro e fazer perguntas em movimento. Muitas vezes, eles esqueciam de esclarecer algo importante e, então, isso emergia nos estágios finais de desenvolvimento e teste, quando ficava especialmente caro consertar e reescrever. De alguma forma, ao final da integração com um parceiro, ele transferiu o status dos empréstimos via API com um atraso de vários dias. Para nós, isso é inaceitável. A parceria teve que ser abandonada.
Agora Escrevemos uma lista de verificação para avaliar a API e os processos que ela serve. A lista de verificação coletou perguntas que devem ser respondidas. Primeiro, nosso gerente procura respostas na especificação. Se não encontrado, endereça perguntas ao parceiro.
A lista de verificação ajuda a encontrar gargalos antes de iniciar o desenvolvimento, e não depois - quando você precisa editar o código e os clientes sofrem de mau serviço.
Nós constantemente reabastecemos a lista de verificação quando nos deparamos com novas situações. Quanto mais detalhada a lista de verificação, menor o risco de ignorar erros no desenvolvimento.
Fragmento de lista de verificação da APIGlossário de Termos
Anteriormente, parecia-nos que, no campo dos empréstimos on-line, todos entendem termos profissionais da mesma maneira, não há discrepâncias. A prática mostrou que estávamos errados.
Por exemplo, com uma IMF, interpretamos clientes primários e repetidos de maneira diferente. Para nós, o cliente principal é o cliente cujo perfil entrou pela primeira vez no banco de dados da IMF por meio do Finspin, e o cliente recorrente já estava no banco de dados. O parceiro considerou clientes repetidos pelo número de empréstimos emitidos: o repeat recebeu dois empréstimos e chegou a um terceiro. Essa confusão terminológica pode levar a inconsistências nas reconciliações financeiras.
Agora usamos um pequeno glossário de termos pelos quais verificamos com os parceiros. Como regra, basta esclarecer cinco ou seis termos básicos para sincronizar idéias sobre integração e avaliar as perspectivas de colaboração.
Uma vez que um glossário de termos nos ajudou a evitar uma integração desvantajosa. Nossa interpretação de "aprovação" foi muito diferente da afiliada. A "aprovação" do parceiro incluiu muitos aspectos diferentes que exigiam processamento manual. Nós nos esforçamos para obter o máximo de automação, e imediatamente nos recusamos a cooperar.
Esclareça o termo "Aprovação"Primeiro negócio, depois desenvolvimento
Havia casos em que começamos a trabalhar com um parceiro em potencial com uma especificação. Nosso gerente recebeu a especificação, estudou-a com cuidado, especificou detalhes para integração com o parceiro, discutiu questões controversas com os desenvolvedores. E então veio uma mensagem da liderança: "Fim, a integração é cancelada, não concordamos com as condições". Os funcionários perderam tempo.
Quando você muda de idéia, e o trabalho é feitoAgora a regra de ferro
está em vigor: o gerente começa a estudar a especificação somente quando recebe uma decisão clara sobre a integração da gerência.
Prontidão para integração: URLs, detalhes, ambiente
Anteriormente, a primeira chamada para a API do parceiro ocorria durante o teste de nosso aplicativo, a partir de servidores de desenvolvimento. Muitas vezes, os primeiros pedidos receberam erros no estágio de configuração da conexão: não é possível conectar ao servidor ou apenas um tempo limite. Razões mais populares:
- Nomes de métodos incorretos (selados ou confusos)
- Domínio inválido
- detalhes de conexão incorretos,
- não adicionou o IP de nossos servidores à lista branca.
Demorou horas para corrigir esses pequenos erros, porque eles foram um após o outro: até você corrigir um, você não verá o próximo.
Agora , antes de levar a tarefa para o plano de desenvolvimento, esclarecemos todos os recursos para acessar a API com uma pequena lista de verificação. A lista de verificação lista os pontos que precisam ser esclarecidos, por exemplo:
- restrições à carga no serviço,
- o número de solicitações por unidade de tempo
- detalhes da conexão
- lista branca por endereços IP,
- Validação de certificado SSL
- requisitos de criptografia de tráfego,
- cabeçalhos especiais em solicitações
- a presença de um servidor de teste com API ou a capacidade de enviar solicitações de teste ao servidor de combate
Se houver uma API de teste, descobriremos definitivamente qual é a diferença ao acessar o servidor de batalha e o servidor de teste. Levamos em conta as diferenças ao criar solicitações de nosso aplicativo para parceiros em ambientes de desenvolvimento e produção. Tais medidas nos ajudam a entender se os sistemas estão prontos para nossas necessidades ou se são necessários ajustes adicionais.
Envio manual de pedidos para a API
Antes, escrevíamos imediatamente o código de acordo com as especificações do parceiro, elaboramos as especificações, revisamos, testamos. E, na fase dos testes de integração, verificou-se que nem tudo escrito na especificação corresponde à realidade - começando pelo formato das solicitações, terminando com o processo de aprovação do aplicativo.
Por exemplo, de acordo com a especificação, ao acessar um determinado método, esperamos uma resposta em um determinado formato na resposta, desligamos o processamento para a validade da resposta recebida, vamos para os testes e, de repente, obtemos uma matriz na resposta. Descobrimos os motivos dos desenvolvedores do parceiro. Eles se referem à documentação desatualizada. Mais uma vez, um círculo de melhorias, revisões e testes.
Agora , assim que recebermos a documentação e os detalhes da conexão, executamos o processo através do cliente da API. Normalmente, o testador faz o upload da especificação para o Postman e simula o processo comercial completo do envio de um pedido de empréstimo, verifica os casos mais populares com diferentes conjuntos de dados para a solicitação. Ou seja, faz manualmente o que o aplicativo fará.
No estágio de uma execução manual, 80% das imprecisões na documentação são reveladas. Descrevemos os erros e passamos para o parceiro. O parceiro elimina imprecisões em casa ou finaliza a especificação. Como resultado, no momento em que o trabalho no código é iniciado, os desenvolvedores recebem documentação de trabalho.
Discrepâncias mais populares:
- formato de solicitação incorreto, promessa de aceitar o json, acabou por precisar de dados do formulário;
- Erros nos nomes dos campos a serem transmitidos na solicitação;
- erros em formatos de campo;
- as regras de validação de campo não são especificadas ou são indicadas incorretamente;
- alguns campos podem ser completamente esquecidos;
- ausente ou diferente da descrição real do formato de resposta do método;
- marcas erradas sobre os campos obrigatórios - “asteriscos” podem aparecer onde o campo não é obrigatório de fato e vice-versa;
- frequentemente não documentados todos os estados e status em que o objeto pode estar;
- discrepâncias entre os estados esperado e recebido dos objetos. Por exemplo, em algum momento, esperamos que o aplicativo esteja no estado X - e pela API, de fato, obtemos Y.
Receita de felicidade: Evitando erros de integração da API
Escreva uma especificação para integração com seu serviço. Passamos dois dias desenvolvendo a especificação no YAML, mas agora estamos economizando dezenas de horas em melhorias e aprovações.
Se o parceiro enviar sua especificação, verifique-a na lista de verificação. Na lista de verificação, colete perguntas às quais você deve receber respostas. Não confie na experiência e na memória, ainda perca alguma coisa.
Tenha um glossário de termos para evitar confusão com seu parceiro. Nossa experiência mostrou que as diferenças podem até estar em termos óbvios.
Não coloque a tarefa em desenvolvimento até receber a aprovação de princípios do gerenciamento da integração com um parceiro. A idéia é óbvia, mas nos ajuda a evitar trabalhos desnecessários.
Abra uma lista de verificação para esclarecer as especificidades do acesso à API do parceiro: detalhes da conexão, lista branca, validação de certificado SSL, requisitos de criptografia de tráfego etc. Verifique a lista de verificação o mais rápido possível para evitar derrapagens nos estágios finais.
Tem uma especificação - não se apresse em escrever código imediatamente. Primeiro, execute manualmente o processo através de um cliente de API, por exemplo, através do Postman. Portanto, você encontrará erros na especificação em um estágio inicial e com pequenos recursos. E eles serão.