O que esperar
O objetivo é mostrar aos desenvolvedores quais problemas os usuários de API estão enfrentando no exemplo de trabalho com vários sistemas de CRM.
Para proteger meu rosto, não divulgarei os nomes dos participantes neste artigo.
Além disso, eu - eu não sou programador da namorada de minha mãe, portanto não tire minhas conclusões para a única opção verdadeira.
Delineador
Era uma vez um garoto esperançoso. Esse garoto não tinha nada em sua vida, exceto trabalhar no suporte técnico de programas de contabilidade. Ele cozinhou neste caldeirão por um longo tempo, até que em um dia ele arrancou o telhado e enviou a principal característica do anfitrião e saiu em busca de perspectivas.
O garoto sempre sonhou em como se tornaria um desenvolvedor legal, ganharia um dinheiro extraordinário, de preferência na moeda Basurm. E, portanto, paralelamente ao trabalho, ele se envolveu na criação de seu site, usando tecnologias sem precedentes, mas com recursos inéditos para aqueles anos. Graças a isso, ele conseguiu encontrar um novo proprietário, que lhe deu um emprego em seu negócio favorito, com um bom salário e perspectivas não realistas.
Desde então, o menino viveu, viveu e fez o bem. E ele não conhecia os problemas e as tristezas ... ou ele sabia? Vamos descobrir!
Consegui um emprego em uma empresa de inteligência de negócios. E que tipo de análise pode ser sem dados? Portanto, a empresa tinha uma equipe separada e, em seguida, um departamento que estava envolvido na coleta de dados dos sites dos clientes para criar agendas de receita a partir de canais de publicidade e outras fontes. Falando sobre os detalhes, meu trabalho era instalar nosso contador nos sites, coletar dados sobre o visitante e criar aplicativos a partir de formulários, bate-papos on-line, retornos de chamada etc. em seus sistemas de CRM. Das quais, no futuro, nossas análises extraíram informações sobre o status e o valor da venda.
E parece não haver nada de complicado aqui, já que a criação de aplicativos no CRM foi simplificada ao envolver nosso sistema, que, usando uma solicitação, criou o aplicativo e o cliente, inclusive assumindo o controle de serviços de terceiros. Mas como você deve entender, essa lógica não difere em flexibilidade. E se o cliente precisava de algo fora do padrão, já era necessário "desligar o modo de conforto" e arregaçar as mangas para trabalhar diretamente com a API do sistema desejado. E, às vezes, trabalhando com a próxima API problemática,
acho que seria melhor permanecer nessas. apoio ...
Problema # 1: falta de métodos / dados
Talvez o problema mais comum que eu tenha encontrado na minha vida seja a falta da capacidade de obter os dados necessários na interface. Conflitos com os clientes constantemente surgiram e continuam a surgir, devido ao fato de que não podemos obter algo que eles veem na tela de seus monitores todos os dias.
Por exemplo, alguns anos atrás, um cliente bastante grande chegou até nós e precisava salvar nos arquivos do CRM que os clientes enviam a ele a partir dos formulários no site. Uma tarefa comum, mas não havia possibilidade de implementação, e não até hoje!
A falha para o cliente foi inaceitável e, no final, tivemos que fazer upload de arquivos, emulando solicitações JS da interface.
Devo dizer que este CRM, autorização na API, também autoriza na interface, o que, para mim, é uma solução bastante estranha. No entanto, graças a isso, não precisamos imitar a autorização usual. Ou foi concebido ...?Outro caso com o mesmo CRM aconteceu há pouco tempo. Era necessário responsabilizar o gerente de aplicativos que está ativo no momento. E como você já entendeu, a API não retorna informações sobre a atividade do gerente para nós. Mas o paradoxo é que a API JS retorna. Como resultado, tive que escrever um aplicativo JS, uma espécie de intermediário, com o qual informei o servidor sobre gerentes ativos no momento.
Solução:Em nossa equipe, é habitual criar um método público de API para a interface e interagir com o servidor por meio dela. Isso elimina o problema de incompatibilidade entre os recursos técnicos da interface e a API pública.
Problema número 2: a falta de um estilo uniforme de solicitações / respostas
Um problema muito comum mesmo em grandes CRMs ocidentais. Suponhamos que precisamos obter uma lista de pedidos por um mês; descobrimos que o sistema tem um limite no número de elementos no upload. E para navegar pelas páginas, você precisa usar o parâmetro offset. Ok, implementamos o método de carregamento de pedidos e, separadamente, o método auxiliar de paginação.
Agora, precisamos descarregar a lista de clientes, estamos implementando um novo método juntamente com o método de paginação escrito anteriormente e ... temos um erro. Como a PM e os desenvolvedores decidiram que o deslocamento parece muito fácil, agora seja compensado por vídeos.
Claro que exagerei, não sei o que aconteceu quando eles escreveram essa API. Mas isso é pelo menos um erro de PM, porque ele não especificou como ele já foi implementado em outros métodos. E também um erro de desenvolvedores, aqueles que escreveram um novo método e aqueles que foram verificados. Por enquanto, todo mundo que usa sua API é forçado a criar muletas em seus aplicativos.
Solução:Qualquer novo método API, se possível, deve corresponder à estrutura dos métodos existentes. O líder técnico (ou líder da equipe por falta do primeiro) pode elaborar um regulamento, um tipo de estilo de código, segundo o qual é necessário desenvolver APIs, e sem deixar de familiarizar todos os desenvolvedores. Se o problema já tem um lugar para estar, então, se possível, é melhor colocar uma muleta do seu lado do que forçar milhares de seus clientes a fazê-lo do seu lado.
Problema número 3: documentação ruim ou falta dela
Documentação é uma referência para desenvolvedores. Muitas vezes, encontramos situações em que somos questionados sobre a possibilidade de implementar um recurso específico. E se não lembrarmos ou não soubermos a resposta, abra imediatamente a documentação. Encontrar informações em um bom diretório é trabalho por alguns minutos, enquanto em um sobrecarregado você pode cavar por meia hora e ainda assim não obterá uma resposta definitiva.
Em alguns casos avançados, é simplesmente impossível encontrar em domínio público. E se você precisar obter uma lista atualizada de métodos, entre em contato com o suporte técnico. E você ainda precisa verificar se algo novo apareceu lá, que pedimos a alguns clientes ...
Solução:Vou citar alguns pontos que, quanto a mim, caracterizam a documentação de qualidade:
- pesquisa por nome, descrição e parâmetros do método
- descrição correta da finalidade do método
- lista de parâmetros aceitos com tipo e descrição
- lista de parâmetros retornados com tipo e descrição
- exemplo de solicitação
- exemplo de resposta
- possíveis códigos de erro com uma descrição
- uma caixa de areia na qual você pode "brincar" com solicitações no modo de design
- alterar histórico de todos os métodos da API para referência rápida
Problema número 4: bicicletas de autorização
Você conhece esse sentimento maravilhoso ao abrir a documentação de um novo sistema e, na seção de autorização, é descrita uma ordem de 3 métodos para obter uma chave válida para apenas 1 solicitação ...? Então, eu não tenho isso.
Resta-me um mistério por que os desenvolvedores abandonam o Oauth 2.0 em favor de suas motos? Tudo bem, se a autorização estiver limitada a um token constante, mas aqui está toda a cadeia de autorização ...
Solução:Você não deve reinventar sua bicicleta quando já houver padrões prontos. De fato, para esses padrões, os desenvolvedores já têm seus próprios componentes para uma autorização simples.
Epílogo
Eu falei sobre quatro problemas que encontrei no início da minha jornada até hoje. Tentei fornecer suas soluções, mas se elas são boas ou não, é para você decidir. No final, cada um de nós tem sua própria arquitetura de pensamento.
Agradeço a todos que leram até agora! Este é o meu primeiro artigo e, se tivesse valor informativo para você, terei prazer em continuar a série de artigos sobre meu sofrimento com a API.
E, é claro, ficarei feliz em ouvir as opiniões de especialistas nos comentários.
Tudo com o próximo 2020!