No entanto, o autor encontrou alguns problemas sérios após o lançamento do projeto :
1. Falta de documentação e especificações completas da API :
· A documentação da API está incompleta e cheia de erros e não pode ser usada como referência precisa.
· Não existe um processo de teste de API acordado, permitindo que a equipe de desenvolvimento de back-end altere e libere a API à vontade, sem aviso prévio. Essas mudanças geralmente são bugs e interrompem a integração com clientes API.
2. Estrutura e validação de API inadequadas :
A equipe de back-end usou uma estrutura Flask inadequada e implementou validação de carga útil complexa por conta própria, a maior parte da qual não foi testada.
· A parte de verificação possui uma grande quantidade de código, incluindo verificação de data, carimbo de data/hora e formato de string, mas não foi totalmente testada, o que retarda seriamente o andamento do projeto.
Portanto , para resolver os problemas acima , é necessário reparar e melhorar a documentação da API para garantir sua precisão e integridade ; estabelecer uma estrutura de API apropriada para melhorar a qualidade e a testabilidade do código e estabelecer especificações rigorosas da API para evitar o lançamento de versões que o façam; não atender às especificações.
Corrija o design e a documentação da API
Pode-se perceber pelos problemas expostos acima que a equipe de desenvolvimento não entende as melhores práticas da API REST e da especificação OpenAPI. Portanto, a equipe de desenvolvimento precisa primeiro entender o OpenAPI e como ele funciona, e integrar a documentação da API na especificação do OpenAPI para ter uma compreensão mais clara do comportamento esperado da API.
No processo de integração da documentação na especificação OpenAPI, descobrimos muitos problemas com designs de API anteriores. Por exemplo, formatos de data personalizados anteriormente exigiam lógica de validação personalizada no servidor e na interface do usuário. Resolvemos esse problema mudando para o padrão ISO suportado pela OpenAPI para representar datas.
Além disso, alguns modos são tão flexíveis que a validação é quase ineficaz. Para melhorar a validação, refatoramos os esquemas e criamos um modelo com diferentes endpoints para cada entidade, tornando-o mais utilizável.
Métodos HTTP e códigos de status foram usados de forma inadequada no design anterior. A equipe usa apenas métodos GET e POST, e todas as respostas retornam um código de status 200. Esse uso indevido torna confuso ao tentar criar, excluir ou atualizar recursos. Para resolver este problema, redefinimos o uso de métodos HTTP e retornamos corretamente o código de status apropriado para indicar com mais precisão o sucesso ou falha da solicitação.
Outra limitação do design anterior era a “reutilização de endpoint”. Embora pareça economizar código, na verdade expõe muitos detalhes de implementação. Portanto, devemos enfatizar o conceito de projetar primeiro a API e depois considerar a implementação.
A fusão da especificação da API com a OpenAPI foi um ponto de viragem importante para o projeto. Depois disso, pudemos executar um servidor simulado para construir e testar a UI antes da integração com o back-end, bem como verificar a implementação do back-end em relação às especificações. Usamos Prism para executar o servidor simulado e Dredd para verificar a implementação do servidor (embora eu prefira usar Schemathesis agora). Isto permite que os projetos se desenvolvam de forma mais clara e eficiente .
Corrigir processo de publicação de API
Mesmo que exista um documento da API, se ele não for testado em relação à especificação da API antes do lançamento, a função do documento se tornará limitada. Embora a documentação em si nos ajude a entender como a API funciona, seu verdadeiro poder reside em sua função como ferramenta de verificação – verificando se o servidor está implementado corretamente.
Para garantir que o servidor API esteja funcionando conforme o esperado, incorporei o conjunto de testes Dredd ao servidor de integração contínua. Ninguém pode mesclar e publicar novo código, a menos que ele passe na validação do Dredd e esteja em conformidade com a especificação da API. Esta etapa permite que a equipe evite modificações inadvertidas no servidor da API. De agora em diante, todas as alterações no servidor precisam ser documentadas com antecedência, e o servidor API deve ter a garantia de seguir essas alterações antes da fusão ou publicação. Essa abordagem garante a estabilidade e consistência do servidor.
Escolha a estrutura de desenvolvimento de API certa
Anteriormente, a equipe implementou o servidor API usando a estrutura Flask, uma estrutura Python popular para construir aplicativos da web. Eles construíram a API com Flask básico e escreveram muitos códigos personalizados para validar a carga útil da API. Este é um erro comum cometido por muitos desenvolvedores de API inexperientes.
Construir uma camada de validação de API personalizada não é indesejável, mas a confiança excessiva nessa abordagem pode levar à reinvenção da roda. A API requer uma lógica de validação complexa para lidar com a carga útil e o URL (caminho e parâmetros de consulta), que devem ser implementados em toda a API. Portanto, se você insistir em construir sua própria camada de verificação de API, acabará produzindo uma estrutura de API. No entanto, existem muitas estruturas de desenvolvimento de API excelentes disponíveis, então por que não escolher uma delas?
Especificamente para o Flask, há várias opções a serem consideradas. Mas nem todas as estruturas são criadas iguais. Por exemplo, flasgger, restx (sucessor de flask-restplus), flask-RESTful e flask-smorest, etc. Com tantas opções, como você toma uma decisão?
Ao escolher uma estrutura de desenvolvimento de API REST, os seguintes fatores devem ser considerados:
· Suporte OpenAPI : A estrutura deve permitir a construção fácil de APIs REST e gerar automaticamente a documentação da API, garantindo a correção da verificação da carga útil. As estruturas de referência incluem Flasgger e flask-smorest.
· Validação robusta de dados : a validação de cargas requer uma biblioteca robusta de validação de dados para lidar com vários atributos e tipos. A biblioteca deve suportar propriedades opcionais e obrigatórias, como formatos de string (data ISO e UUID), bem como validação de tipo estrita e relaxada. No ecossistema Python, pydantic e marshmallow são excelentes bibliotecas de validação de dados, e Flasgger e flask-smorest podem usar marshmallow.
· Validação abrangente : a estrutura deve suportar validação de cargas úteis de solicitação, cargas úteis de resposta, parâmetros de caminho de URL e parâmetros de consulta de URL. Algumas bibliotecas podem apenas validar a carga útil da solicitação e ignorar os parâmetros de URL ou a carga útil da resposta. Certifique-se de que a estrutura forneça pelo menos uma maneira de impor regras de validação. Se estiver usando marshmallow, a carga útil da resposta pode ser verificada diretamente usando seu modelo.
· Maturidade : Escolha uma biblioteca que seja madura, estável e tenha apoio ativo da comunidade. Deve ter boa documentação e capacidade de resolver rapidamente os problemas do usuário.
Depois de avaliar os fatores acima, selecionamos flask-smorest, um plug-in Flask que suporta o uso de marshmallow para construir facilmente verificação de dados para APIs REST. Pode simplificar o processo de verificação de dados e reduzir a quantidade de código personalizado. As cargas de solicitação e resposta agora são validadas corretamente, e o marshmallow também lida com a validação de consultas de URL e parâmetros de caminho.
Escolher a estrutura de API certa nos permite ter uma API funcional. Como a estrutura lida com os detalhes da camada API, podemos nos concentrar mais na lógica de negócios e no modelo de dados do aplicativo, resultando em maior velocidade de desenvolvimento e na capacidade de lançar software melhor com mais frequência.
Considere tudo para construir uma ótima API
Na Internet de hoje, as APIs estão em toda parte e são inevitáveis. No entanto, construir verdadeiramente uma boa API é uma tarefa complexa. Assim como escrever um código legível e fácil de manter, construir uma interface de alta qualidade, fácil de usar e de modificar também é um desafio no desenvolvimento de API.
Fornecer uma API de alta qualidade é difícil porque ela precisa ser consistente com os requisitos do negócio, ou seja, o cliente e o servidor devem usar as mesmas convenções e especificações, caso contrário, a integração será difícil de ser alcançada.
Alcançar esse objetivo requer considerar vários aspectos: reunir os requisitos do cliente, traduzir os requisitos em detalhes técnicos, projetar a API, escrever a documentação, escolher uma estrutura de API apropriada e usá-la corretamente, testar a API e garantir que a implementação atenda às especificações de design. Isso não inclui aspectos como segurança, implantação e operação de API.
Quando se trata de construir APIs críticas para os negócios, o conselho é não deixar isso apenas para desenvolvedores juniores. Eles podem participar, mas é necessário um desenvolvedor sênior para orientar seu trabalho. Se você não tem experiência em desenvolvimento de API, siga as práticas recomendadas: primeiro projete a API, depois escreva a documentação, implemente-a de acordo com a especificação e verifique-a. Não reinvente a roda, escolha a estrutura certa!
Embora possa levar algum tempo para aprender OpenAPI, entender a estrutura de teste de API, pesquisar a estrutura de desenvolvimento de API, etc., vale a pena. Caso contrário, você ficará preso em um ciclo vicioso de integração de API e problemas de qualidade de software que prejudicarão o andamento do projeto e incorrerão em custos enormes para corrigir problemas.
Se você tiver recursos suficientes e desenvolvedores de API experientes, a probabilidade de construir a API corretamente aumentará bastante e você poderá economizar muito dinheiro. Além disso, devemos também prestar atenção à gestão de APIs. Muitos problemas residem não apenas no desenvolvimento inicial e nos custos de despesas, mas também em problemas de código ocultos durante o processo de desenvolvimento e transferências pouco claras de funcionários responsáveis, que podem causar perigos ocultos. Portanto, Power Simple Integration acredita que o gerenciamento de API pode usar ferramentas de terceiros para gerenciar APIs de uma só vez, envolver múltiplas funções, evitar fugir de responsabilidades e melhorar a eficiência do desenvolvimento.