O que é o modelo de maturidade da API?

Alguns frameworks de maturidade de API enfatizam dimensões específicas, como segurança, facilidade de descoberta, capacidade de manutenção ou engenharia de plataforma. Os fornecedores de gerenciamento de API, incluindo Kong, Tyk e Curity, oferecem modelos de maturidade de API alinhados com suas próprias soluções, ajudando os clientes a avaliar seu progresso na adoção dessas plataformas. Outros modelos têm um escopo mais amplo e podem ser aplicados a qualquer protocolo ou arquitetura.

As interfaces de programação de aplicativos (APIs), que facilitam as conexões entre serviços e aplicações separados, são um pilar fundamental da internet, ajudando os desenvolvedores a usar tecnologias e fontes de dados de terceiros, em vez de criá-las a partir do zero. Elas também permitem a integração de recursos, dados, segurança e governança dentro das organizações, simplificando as implementações internas e as comunicações entre equipes. Várias APIs podem ser empacotadas junto com bibliotecas, ferramentas de IU e outros componentes para formar um kit de desenvolvimento de software(SDK), um conjunto de ferramentas que ajuda os desenvolvedores a criar aplicações padronizadas de forma rápida e confiável.

Os modelos de maturidade de API identificam e descrevem inovações estruturais e tecnológicas específicas, bem como as melhores práticas estratégicas que podem ajudar as organizações a desenvolver sistemas de API mais sofisticados e robustos, melhorando a eficiência, a segurança e a interoperabilidade. Eles servem como um roteiro que ajuda as organizações a decidir quais inovações priorizar à medida que aceleram o desenvolvimento da API.

O modelo de maturidade de Richardson, um dos frameworks mais citados, avalia a adesão de uma API aos princípios RESTful em quatro níveis de maturidade, com o nível mais alto representando um sistema totalmente RESTful.

Em 2000, o cientista da computação Roy Fielding introduziu o REST, um estilo de arquitetura que promove funcionalidades como interface uniforme, desacoplamento cliente-servidor, ausência de estado, capacidade de armazenamento em cache e sistemas em camadas. Juntos, esses recursos podem melhorar a escalabilidade, a eficiência e a flexibilidade nas organizações e podem contribuir para uma internet mais aberta, resiliente e segura quando implementados em larga escala. As iterações modernas geralmente usam HTTP para transportar informações e o formato JSON legível por humanos para organizar esses dados, embora outros protocolos e formatos também possam ser usados.

Em 2008, o engenheiro de software Leonard Richardson desenvolveu esse framework com um modelo que identifica mudanças técnicas específicas que as organizações podem implementar para melhorar a adaptabilidade e a resiliência de seu projeto de API REST. O modelo de maturidade de Richardson (RMM) "incentiva você a olhar para as três tecnologias da web – URI, HTTP e hipermídia (também conhecida como HTML) – como três tecnologias individuais em vez de um pacote", disse Richardson ao IBM Think. O framework mostra os benefícios práticos da implementação gradual de cada uma delas, "dado que temos essas tecnologias, elas são muito populares e são amplamente compatíveis com todas as linguagens de programação".

O modelo de maturidade de Richardson prioriza a implementação de recursos, onde cada recurso recebe um URI distinto, de acordo com os princípios gerais do REST, que recomendam atribuir a cada recurso uma identificação única. O RMM também incentiva o uso de documentos de resposta, que capturam o estado atual de uma API, em vez de documentos de descrição, que apresentam uma descrição estática e predefinida de uma API em um único ponto no tempo. O modelo geralmente se aplica a aplicações web baseadas em HTTP, embora como estrutura conceitual ele também possa ser utilizado em outros contextos, como redes IoT e pipelines de dados.

O modelo de maturidade de Richardson usa quatro níveis para distinguir entre diferentes graus de maturidade, de uma arquitetura não RESTful a uma arquitetura totalmente RESTful.

O nível zero representa um design não RESTful, apresentando um único endpoint (como “/api”) e um único comando (geralmente POST). Embora o nível zero seja simples de implementar, ele não consegue utilizar as funcionalidades mais poderosas do HTTP, incluindo verbos, URIs e códigos de status. Em vez disso, o HTTP é usado meramente como um mecanismo de transporte, com todos os detalhes operacionais adicionados ao próprio corpo da mensagem.

Como os padrões de chamada de procedimento remoto (RPC) baseados em XML historicamente empregaram esse método, os críticos o apelidaram de "pântano de POX" (XML simples). A ideia é que, com a falta de estrutura e sem delimitações claras entre os serviços, as funções e os dados podem facilmente se tornar confusos e fortemente interligados. No nível zero, a API não tem capacidade de identificar ou expor recursos detectáveis, forçando os consumidores de API a saber com antecedência o que está disponível. Os desenvolvedores podem ter dificuldades com a escalabilidade, controle de versão e resolução de problemas porque o endpoint único não consegue compartilhar informações sobre si mesmo.

O nível um apresenta vários URIs, cada um capaz de representar um recurso diferente. Mas ele continua usando apenas um único verbo HTTP, normalmente POST. Em vez de interagir com um endpoint genérico “/api”, os clientes agora podem chamar endpoints que correspondem a recursos específicos – por exemplo, “/products”, “/carts” ou “/invoices” em uma configuração de comércio eletrônico. No entanto, normalmente os clientes ainda precisam expressar a intenção operacional ou as ações por meio do próprio corpo da solicitação, em vez de usar um conjunto predefinido de verbos HTTP.

Essa abordagem estabelece linhas mais claras entre os recursos e reduz as ambiguidades sobre quais recursos estão disponíveis para os clientes. Mas os desenvolvedores podem facilmente confundir quais ações podem ser executadas porque não há um formato padronizado para chamar URIs. O nível um também pode se tornar complicado com o tempo porque, na prática, os desenvolvedores podem criar novos endpoints para ações individuais, como “/productsUpdate” ou “/productsDelete”. Essa abordagem pode fazer com que os URIs se acumulem gradualmente, tornando as implementações e o controle de versões mais desafiadores.

Por fim, o modelo torna os desenvolvedores mais dependentes da documentação externa da API porque, embora os recursos recebam URIs distintos, eles não podem expor quais ações podem ser interpretadas ou executadas.

O nível dois adiciona métodos HTTP, um conjunto padronizado de verbos que os desenvolvedores podem usar para interagir com dados e serviços. Em muitas configurações, os clientes podem usar quatro comandos básicos (criar, ler, atualizar ou excluir) para executar diferentes ações em cada endpoint. Os cabeçalhos podem ser usados para transmitir informações adicionais, como tipo de conteúdo, requisitos condicionais ou credenciais de autorização, durante a chamada da API.

Essa abordagem é mais eficiente e organizada em comparação com o nível um e o nível zero porque os usuários têm uma noção do que a API é capaz e como os clientes podem interagir com ela. Mas as APIs não conseguem transmitir essas informações em tempo real – os usuários só podem aprender sobre cada API por meio de um portal do desenvolvedor externo – reduzindo a descoberta. Essa abordagem estática também pode levar a desalinhamentos se a documentação da API não corresponder aos recursos atuais.

Atualmente, os ecossistemas da API da maioria das organizações operam no nível dois porque a camada oferece um equilíbrio entre previsibilidade, eficiência e acessibilidade. Também permite que as organizações aproveitem os recursos de infraestrutura distintos do HTTP, como cache (armazenar no local recursos usados com frequência, para que possam ser recuperados rapidamente), levando a ganhos significativos de desempenho.

O nível três introduz o HATEOAS, ou hipermídia, como o mecanismo do estado da aplicação. Quando um cliente faz uma chamada de API, a API responde com uma lista dinâmica de opções para várias ações e termos relacionados, da mesma forma que os navegadores modernos operam. Essas ações e termos são transmitidos em banda, o que significa que os desenvolvedores não precisam consultar a documentação externa para aprender sobre eles. As arquiteturas baseadas em hipermídia também promovem a interoperabilidade porque os clientes externos podem acessar facilmente os serviços sem aprender a usá-los com antecedência.

Ao mesmo tempo, os controles hipermídia introduzem maior complexidade no tempo de execução: "O cliente tem que ser capaz não apenas de reagir de forma pré-programada, mas ser capaz de ler os documentos que chegam do servidor e usar o conteúdo desses documentos para tomar a decisão sobre sua próxima solicitação", disse Richardson.

Criar e manter recursos de hipermídia pode ser mais caro e demorado devido à estrutura dinâmica da hipermídia. A API responde às solicitações do cliente com um conjunto de links para ações adicionais, o que exige mais recursos operacionais. Além disso, muitas plataformas de clientes não oferecem suporte a hipermídia, portanto, quando uma organização adota o HATEOAS, os usuários externos podem ter que encontrar ferramentas compatíveis antes de poderem acessar esses serviços.

Hoje, o HATEOAS é usado com mais frequência por bibliotecas, organizações sem fins lucrativos, instituições científicas, coalizões de mercado ou empresas insurgentes (organizações que buscam desestabilizar setores), disse Richardson, porque promove a abertura e a interoperabilidade. A hipermídia também pode ser eficaz quando usada internamente, pois facilita a descoberta de APIs e ações pelos usuários, mesmo aqueles que não possuem conhecimento prévio do ecossistema de APIs. Algumas empresas podem oferecer APIs de hipermídia durante sua fase de crescimento e restringir o acesso após o início da monetização do produto.

O setor está mudando cada vez mais para alternativas como GraphQL e gRPC para casos de uso específicos. Embora 93% dos desenvolvedores afirmem que usam serviços web RESTful de alguma forma, de acordo com o relatório State of the API da Postman, um terço agora usa GraphQL e 14% usam gRPC. O GraphQL consegue buscar de forma inteligente solicitações de múltiplos microsserviços, mesmo serviços hospedados em ambientes diferentes, e compilá-las em uma única resposta, aumentando a eficiência e evitando o provisionamento excessivo ou insuficiente. O gRPC, por sua vez, é ideal para streaming, telemetria e outros casos de uso em que o alto desempenho e a baixa latência são as principais preocupações.

Embora o GraphQL e o gRPC não possam replicar a natureza dinâmica da hipermídia, ambas as arquiteturas lidam com pontos problemáticos relacionados à eficiência e ao gerenciamento de esquemas com mais precisão, levando algumas organizações a priorizar essas implementações em detrimento de controles de hipermídia completos.

No modelo de maturidade de Richardson, a transição de um nível de maturidade de API para o próximo pode apresentar desafios tanto de projeto quanto técnicos. O processo geralmente envolve a refatoração do código do servidor para acomodar vários URIs (nível um) e vários métodos HTTP (nível dois). Isso é alcançado atualizando as regras de roteamento, interações com bancos de dados, testes, documentação e controladores.

As organizações podem começar catalogando seus endpoints atuais, identificando quais podem ser modificados para seguir as restrições do RESTful e mapeando os recursos e verbos necessários. Os desenvolvedores podem criar uma nova versão com base na versão atual da organização, para que as chamadas dos clientes não sejam interrompidas durante a transição. Um conjunto abrangente de códigos de erro também pode ajudar os usuários a aprender como navegar em novos endpoints de API e solucionar erros sem consultar uma documentação excessiva.

Enquanto o RMM se concentra em implementações tecnológicas específicas em sistemas RESTful, os modelos organizacionais adotam uma visão mais ampla, ajudando as empresas a se alinharem em torno de um conjunto compartilhado de princípios que promovem consistência, otimização de recursos e adaptabilidade. Embora os frameworks de maturidade estratégica possam diferir de acordo com a organização, uma abordagem comum incorpora quatro níveis:

Em ecossistemas de API básicos ou ad hoc, as organizações reagem a preocupações imediatas em vez de trabalhar sob um framework coesivo de desenvolvimento de API. Os desenvolvedores criam e desativam APIs conforme necessário, com controle centralizado limitado, o que pode levar a desalinhamentos, além de problemas de governança, segurança e observabilidade. Com poucos insights sobre o desempenho atual das APIs, as equipes não conseguem alocar recursos de forma eficaz nem planejar o futuro.

Os ecossistemas de API padronizados apresentam uma documentação consistente, convenções de nomenclatura, códigos de erro e padrões de projeto. Um API gateway pode ser usado para impor autenticação, autorização e outros protocolos centralizados de segurança de API. Os desenvolvedores podem adicionar, remover e manter APIs com confiança dentro da estrutura de governança da organização e podem reutilizar e adaptar componentes sem dificuldades. Os clientes podem descobrir e aprender facilmente sobre os serviços disponíveis por meio de um portal do desenvolvedor e integração, aumentando a adoção geral da API.

No entanto, como existem poucos mecanismos para avaliar o desempenho e a segurança das APIs nesta fase, as equipes podem ter dificuldades em manter o controle sobre o ecossistema. Por exemplo, uma organização pode não ter conhecimento de violação de segurança, erros de versão ou problemas de autenticação dentro de um determinado cluster de API.

Os frameworks gerenciados usam dados de telemetria, KPI e outras métricas para capturar o desempenho da API com mais detalhes. Por exemplo, um sistema de monitoramento pode alertar os desenvolvedores quando os clientes enfrentam downtime excessivo da API e ajudar a identificar o problema subjacente, seja sobrecarga do servidor, interrupções de rede, desalinhamentos de código ou outro problema.

Os ecossistemas gerenciados também podem ter funcionalidades de infraestrutura de governança de API mais avançada, que preserva a autonomia da equipe e, ao mesmo tempo, oferece aos stakeholders uma compreensão clara de quais APIs eles são responsáveis por gerenciar. Por fim, os ecossistemas gerenciados introduzem processos formais de gerenciamento do ciclo de vida, nos quais as APIs são monitoradas durante as fases de projeto, desenvolvimento, manutenção, controle de versão e desativação. Mas, nesse nível, as organizações podem ainda não ter uma visão coesiva de como o gerenciamento de API contribui para objetivos de negócios mais amplos.

Os framework otimizados ou estratégicos combinam governança, padronização, gerenciamento do ciclo de vida, métrica e melhores práticas de segurança com o planejamento de negócios de longo prazo. Com a supervisão de toda a rede, as organizações podem escalar e alocar recursos de forma eficiente e responder dinamicamente às mudanças nas condições do mercado. Em vez de pensar nas APIs apenas como componentes técnicos, as organizações podem implementá-las em serviço de objetivos de negócios mais amplos. Os frameworks estratégicos ajudam as organizações a criar roteiros e estratégias de planejamento com visão de futuro, acelerando a inovação e melhorando a eficiência operacional.

As organizações podem criar modelos de maturidade de API para lidar com pontos problemáticos ou focos operacionais específicos. As áreas de foco comuns incluem:

Esses modelos de maturidade se concentram nos princípios de projeto de APIs, como a adoção de protocolos, práticas e padrões específicos que contribuem para uma melhor experiência do usuário. O RMM é um exemplo de framework baseado em design, mas outros modelos podem se concentrar no GraphQL, gRPC e outros estilos de arquitetura.

Os modelos de governança se concentram no grau em que as organizações conseguem manter o controle e a supervisão sobre seus ecossistemas de APIs. Nos níveis mais altos, as organizações mantêm uma alta conformidade, qualidade de dados e segurança, ao mesmo tempo em que preservam a autonomia dos stakeholders.

Os frameworks baseados em governança também consideram a qualidade dos mecanismos de aplicação de um ecossistema de APIs, inclusive se incorporam verificações automatizadas e processos de validação. Os modelos de propriedade, por sua vez, atribuem APIs a equipes específicas para que cada API seja contabilizada.

Os frameworks de maturidade focados em segurança avaliam a adesão de uma rede de APIs às melhores práticas de segurança. Nos estágios iniciais, as organizações podem contar com chaves de API ou autenticação HTTP básica, que não possuem controle granular e são vulneráveis à exposição. Sistemas avançados podem introduzir autenticação e autorização baseadas em token, bem como acesso zero-trust. Os frameworks mais sofisticados seguem os princípios de gerenciamento de acesso e identidade, como o uso dos protocolos de autorização OAuth e OpenID Connect (OIDC).

Os documentos de API são guias técnicos que fornecem instruções sobre como os desenvolvedores podem usar e integrar uma API específica. A documentação pode incluir tutoriais e exemplos de código, bem como notas de versão e parâmetros de chamada aceitáveis.

Inicialmente, as organizações podem não ter um processo padronizado para criar e manter a documentação de APIs, dando aos desenvolvedores poucas informações sobre o que cada API é capaz de fazer. Níveis mais elevados podem introduzir formatos padronizados para descrever especificações de APIs, como a Especificação OpenAPI (OAS) ou o API Blueprint. Frameworks de API maduros também podem incorporar automação, ajudando a garantir que a documentação seja atualizada automaticamente junto com cada implementação.

Os modelos de maturidade focados em observabilidade ajudam as organizações a acompanhar a sofisticação de seus mecanismos de coleta de dados em microsserviços. Os sistemas básicos podem usar telemetria e métricas para ajudar as organizações a identificar erros, mas não conseguem ajudar a identificar tendências de dados de longo prazo.

Plataformas mais complexas podem rastrear proativamente a latência, as taxas de solicitação e outras métricas relevantes para ajudar as organizações a responder antecipadamente a downtime, desalinhamentos e outros problemas. No nível mais alto, as organizações podem identificar padrões de dados de alto nível e gerar insights praticáveis que orientarão o desenvolvimento futuro da API.