API - Guia de Estilo

Princípios

442 views 29/03/2018 12/04/2018 admin 7

Sendo a plataforma orientada a micro-serviços e habilitada para a nuvem alguns benefícios estratégicos e princípios de design considerados.

Benefícios estratégicos

  • Aumento na interoperabilidade: permitindo que os serviços estejam acessíveis a consumidores das mais variadas plataformas e tecnologias;
  • Aumento na federação: permitindo que diversos serviços trabalhem juntos sem perder a autonomia e governança individual;
  • Aumento nas opções de fornecedores: dando a possibilidade de uso da tecnologia e fornecedor mais adequado à problemática do negócio;
  • Aumento no alinhamento da TI com a área de Negócio: permitindo maior flexibilidade dos recursos de tecnologia para atender o negócio;
  • Aumento no retorno sobre o investimento (ROI): permitindo que domínios e serviços menores permitam diferentes composições e menor custo de operação e manutenção;
  • Aumento na agilidade organizacional: permitindo maior eficiência em aplicar mudanças no negócio como reorganização e composição de serviços;
  • Aumento na eficiência da TI: permitindo reduzir o peso e entrave da TI para a operacionalização do negócio.

Princípios de Design

Cada serviço construído deve considerar os seguintes princípios quando realizado a sua construção. Sendo que na prática é difícil que todos eles sejam aplicados em sua plenitude, tendo situações onde um serviço pode atender mais ou menos cada um dos princípios, mas sempre buscando atendê-los.

Contract-first

Toda funcionalidade de negócio deve possuir um contrato formal e padronizado expressando o objetivo e competência do serviço de forma consistente.

Além disto, o contrato formal deve ser definido antes da implementação em si, de modo que o negócio seja atendido pelo contrato e que detalhes de implementação não o “sujem”.

No caso do desenvolvimento com a plataforma, o contrato do serviço pode ser definido na SDL (Service Definition Language), o qual gera a documentação utilizando a especificação OpenAPI (Swagger).

Baixo acoplamento

Todo serviço deve avaliar em sua capacidade de ser independente de outros serviços para realizar sua função de negócio.

Dependência entre serviços será algo comum, então é importante avaliar a possibilidade de eliminá-los ou prever no design do serviço como ele irá lidar com questões como indisponibilidade do outro serviço, cache das informações trocadas, etc.

Abstração

Todo serviço deve esconder os detalhes de implementação, permitindo assim que futuramente o mesmo contrato seja respeitado mesmo que toda implementação seja substituída por outra tecnologia. O mesmo vale para o consumidor, onde o serviço não deve exigir uma tecnologia específica (java, python, etc) para o consumidor.

Reusabilidade

Todo serviço deve objetivar atender uma determinada regra de negócio que possa ser aproveitada por mais de um processo de negócio e clientes, evitando especificidades de um único cliente ou consumidor. Por exemplo, um serviço não deve objetivar atender uma regra de negócio que serve apenas para uma determinada tela do sistema, ela deveria atender à funcionalidade de negócio de forma mais genérica.

Seguindo este princípio, o retorno sobre o investimento (ROI) é maior, pois um mesmo esforço de implementação e manutenção do serviço pode atender não apenas a uma tela específica do sistema, mas também outros cenários e processos de negócio, gerando economia e agilidade à empresa.

Alguns cenários específicos de serviços sacrificam este princípio em prol de aumento de performance e economia de recursos da infraestrutura, como por exemplo, a criação de serviços específicos para atender o front-end, o mobile, etc. Este tipo de implementação pode ser válido, desde que tomada a decisão de design de forma consciente e preferencialmente, ser uma composição de um serviço mais genérico.

Autonomia

Assim como o princípio de baixo acoplamento, as dependências externas em um serviço possuem papel fundamental no sucesso ou falha de autonomia de um serviço. Pois quanto mais recursos compartilhados este serviço utilizar, menor será a sua autonomia em cumprir a funcionalidade de negócio.

Neste princípio podemos considerar e avaliar o quanto o serviço é autônomo para funcionar, escalar e suprir as informações necessárias ao negócio. Quanto mais autônomo melhor.

Sem estado

Este princípio visa garantir que o serviço atenda a funcionalidade de negócio com o melhor desempenho e isolamento possível. Sendo que o serviço e o consumidor não deveria ter de conhecer o histórico de execução anterior para conseguir entregar a funcionalidade de negócio esperada.

Todo serviço deve ser Stateless sempre que possível, principalmente por considerarmos o ambiente de nuvem e containers, onde servidores podem ser adicionados ou removidos do cluster que atende à funcionalidade de negócio, e neste caso, não deveriam guardar qualquer estado de execução.

Descoberta

Ao criar uma API, devemos conseguir que diversos consumidores possam usufruir desta funcionalidade de negócio, da forma mais autônoma e prática possível. Pois quanto mais gente utilizando, melhor o retorno sobre o investimento de desenvolvê-lo.

Para ajudar neste princípio, o portal de desenvolvimento expõe todas as APIs, documentação, guias de uso e outras informações que permitem a qualquer pessoa encontrar uma API existente e aprender como utilizá-la, independente da tecnologia envolvida. Por isso, é importante que no desenvolvimento de uma API as documentações sejam descritas e o mais claras e completas possíveis.

Composição

Este princípio consiste em criar serviços que sejam capazes de trabalhar em grupo com o objetivo de resolver um problema de negócio maior. No dia a dia, os conceitos de orientação a objetos e de domain-driven design ajudam a construir serviços que dividem um problema de negócio grande em pedaços menores, mais fáceis de desenvolver e de manter e que, trabalhando juntos conseguem resolver o problema maior. Além disto, permite que sejam a composição possa ser formada ou alterada ao longo do tempo, conforme o problema de negócio muda.

Customização

Um último princípio que está associado aos diferencias dos produtos Senior. A capacidade de atender algumas especificidades de cada cliente com recursos de customização. Sendo assim, ao criar serviços como de Entidades, é importante prever a necessidade ou não de suportar customizações ou ainda, em endpoints da necessidade ou não de acionar um ponto de extensão durante a regra de negócio.

Este artigo foi útil para você?