Por que os esforços da plataforma API não funcionam?

Sua iniciativa de plataforma API não conseguiu entregar os resultados de negócios esperados. A adoção por clientes e usuários internos estagnou. Eu estive no seu lugar.

Com base em minha experiência anterior trabalhando na iniciativa de plataforma de API do LiveRamp, vou me aprofundar no que funcionou e no que não funcionou e, em seguida, discutirei problemas comuns que as equipes de plataforma de API enfrentam e como você pode resolvê-los.

Enquanto eu estava na LiveRamp, experimentamos um crescimento explosivo, passando de menos de 100 engenheiros para mais de 500 em apenas dois anos. Essa rápida expansão trouxe atritos internos e levou ao envio de produtos aos clientes em um ritmo mais lento. Para combater isso, decidimos construir uma plataforma de API para agilizar a forma como as equipes lançam novas APIs.

Nosso objetivo era agrupar todos os requisitos comuns, como autenticação, documentação, implantação, etc., em uma experiência perfeita para o desenvolvedor. O escopo deste projeto acabou sendo maior do que se esperava, em grande parte devido à escassez de ferramentas disponíveis para a construção de APIs REST de nível empresarial.

Essa experiência me levou a fundar o Speakeasy. Eu estava determinado a usar meu aprendizado no LiveRamp para criar o conjunto de ferramentas necessário para construir a plataforma API.

Construindo uma plataforma API em 2019

Nosso objetivo North Star era possibilitar que um novo contratado integrasse, projetasse, construísse e enviasse um novo serviço em uma semana. Pública ou interna, não importava. Para atingir esse objetivo agressivo, projetamos nossa plataforma para funcionar como uma incubadora de API: os designs de serviço chegariam e uma API totalmente pronta e disponível em produção sairia do outro lado.

A incubadora de API cuidaria de:

• Criação de especificação OpenAPI: Uma linguagem específica de domínio (DSL) personalizada com estilo inspirado no Smithy da Amazon deveria remover a carga da equipe para entender o formato OpenAPI. A incubadora de API criaria as especificações para o engenheiro.
• Governança: Para manter a consistência, desenvolvemos um fluxo de trabalho de governança rigoroso que garantiu que as APIs aderissem aos princípios RESTful, às convenções de nomenclatura, aos padrões de segurança e aos regulamentos de privacidade de dados. Nossa plataforma automatiza grande parte do processo de governança, aplicando essas regras na fase de design por meio de nossa DSL personalizada e durante pipelines de CI/CD.
• Esboços de servidor: Para garantir uma transição perfeita do projeto à implementação, nossa plataforma gerou stubs de servidor fora do DSL. Esses stubs eram versões básicas da API com endpoints roteáveis, manipulação de solicitações e respostas simuladas. Isso permitiu que os desenvolvedores começassem a trabalhar na lógica de negócios imediatamente, sem esperar que toda a infraestrutura da API fosse configurada.
• Autenticação: Uma camada proxy foi construída para se comunicar com o gateway API do LiveRamp. O componente de autenticação verificava a identidade dos usuários ou serviços que tentavam acessar as APIs, garantindo que apenas consumidores autorizados pudessem interagir com os terminais da API.
• Roteamento: A funcionalidade de roteamento direciona as solicitações de API recebidas para os serviços de back-end apropriados com base no caminho da solicitação, nos parâmetros ou nos cabeçalhos. O roteamento eficiente é crucial para gerenciar o tráfego e garantir que o terminal de serviço correto lide com as solicitações.
• Cadastro: O registro no gateway de API foi essencial para integrar os serviços de API ao ecossistema mais amplo de gerenciamento de API. Essa etapa tornou as APIs detectáveis ​​e gerenciáveis ​​por meio do gateway, facilitando o controle de tráfego, o monitoramento e a aplicação de políticas.

Estávamos construindo durante o auge da moda dos microsserviços e nos concentramos fortemente na construção da infraestrutura que nos permitiria lidar com a escala.

Em retrospectiva, talvez tenhamos sido mais bem servidos construindo ferramentas focadas em garantir robustez e fácil integração – o que hoje é chamado de “experiência do desenvolvedor”.

Algumas coisas que deveríamos ter pensado:

• SDKs: Nada melhora a velocidade da integração de API como os SDKs. Bibliotecas nas linguagens de programação preferidas do usuário podem aumentar o tempo para 200 em até 60%. Os desenvolvedores podem se concentrar na criação de recursos importantes, em vez de lidar com as nuances das solicitações HTTP e do tratamento de respostas. Perdemos completamente este. Deixamos que cada equipe desenvolvesse seus SDKs, o que significava que a qualidade dos SDKs e sua interface eram inconsistentes. As equipes tiveram dificuldade para se integrar às nossas APIs, tanto interna quanto externamente.
• Teste de contrato: A base de um ecossistema de API contínuo é garantir que tanto a API quanto seus consumidores cumpram os contratos predefinidos. A implementação de testes de contrato rigorosos reduz as dores de cabeça de integração, garantindo que quaisquer alterações na API não interrompam inesperadamente os aplicativos de consumo existentes. É semelhante a um pacto de confiança entre sua API e seus usuários, prometendo que continua sendo uma base confiável sobre a qual eles podem construir com confiança à medida que sua API evolui. Este foi um ponto cego na nossa estratégia, levando a desafios de integração e a uma falta de confiança na estabilidade e previsibilidade do comportamento da nossa API ao longo do tempo.
• Observabilidade: A transparência na dinâmica operacional da API não é apenas benéfica, é indispensável. Fornecer aos desenvolvedores ferramentas para observabilidade — incluindo registro detalhado, monitoramento em tempo real e rastreamento preciso — transforma a depuração de uma tarefa tediosa em uma vantagem estratégica. Ele permite que os usuários identifiquem problemas rapidamente, entendam os padrões de uso e otimizem as interações da API. Nossa negligência em adotar totalmente a observabilidade fez com que os desenvolvedores muitas vezes navegassem no escuro, dificultando o diagnóstico de problemas e a otimização das interações de seus aplicativos com nossas APIs.
• Versionamento: O controle de versão de API bem pensado é a base para equilibrar inovação com estabilidade. Uma estratégia de controle de versão clara e consistente garante que as melhorias e expansões não ocorram às custas das integrações existentes. Respeita a necessidade de previsibilidade dos desenvolvedores, permitindo-lhes atualizar em seu próprio ritmo, sem medo de interrupções repentinas. Nossa abordagem subestimou esse aspecto, resultando em atritos desnecessários para os desenvolvedores, pois eles enfrentavam desafios inesperados para manter a compatibilidade com nosso cenário de APIs em evolução.

Nossa abordagem foi muito focada nos aspectos internos do desenvolvimento de APIs. Estávamos construindo uma plataforma que facilitaria aos nossos engenheiros a construção e implantação de APIs. Não nos concentramos em facilitar a integração dos usuários com nossas APIs. Esta foi uma grande falta.

O que foi bem

Conseguimos acelerar dramaticamente a construção de novos serviços no LiveRamp. Depois que uma equipe adotou a plataforma API, novos serviços levaram cerca de três dias para serem implantados em produção. A maior parte desses ganhos veio da automatização da criação da documentação e do cadastro no API gateway.

A camada proxy foi importante para reforçar os recursos da nossa plataforma API muito além da aceleração inicial da implantação do serviço. Serviu como primeira linha de defesa, implementando medidas de segurança robustas que incluíam terminação de SSL, limitação de taxa e lista branca de IP para garantir que todo o tráfego de entrada fosse autenticado e autorizado antes de chegar aos nossos serviços de back-end. Essa camada foi fundamental na proteção contra ameaças e vulnerabilidades comuns à segurança.

Nossa camada de governança também foi um sucesso. Foi difícil configurá-lo, mas, uma vez implementado, nossas regras de linting garantiram que nossas APIs fossem consistentes e aderissem às práticas recomendadas.

Portanto, nossos sistemas funcionaram e a produção de API era uma máquina bastante bem lubrificada depois de iniciada. Mesmo assim, não estávamos vendo o impacto comercial que esperávamos. Tanto interna quanto externamente, a adoção acabou se tornando um gargalo para a eficácia do nosso programa.

O que não deu certo

Em retrospectiva, o DSL não era a escolha tecnológica certa. Fomos vítimas daquela tentação comum dos engenheiros: o desafio técnico excitante, mas de baixo valor. Construir a DSL foi muito divertido, mas, em última análise, contraproducente. OpenAPI não é perfeito, mas é, por uma grande margem, a interface ideal para definir uma interface REST. A adoção interna de nossa plataforma API demorou mais do que o previsto devido à resistência interna em aprender uma nova DSL. Cada vez que um novo contratado era contratado, essa situação se repetia. Eles perguntavam: “Posso simplesmente escrever OpenAPI?”

Como previsto, a segunda (e maior falha) foi o foco na escala em detrimento da experiência do usuário. Você pode criar o serviço mais útil do mundo, mas se não for fácil de integrar, ninguém o utilizará.

Nossas APIs públicas, em particular, tiveram dificuldades para serem adotadas. Para nossos clientes, a integração com nossa API foi planejada para o próximo trimestre, próximo mês, próxima semana — sempre no roteiro, nunca priorizada. O problema era que era simplesmente muito difícil de integrar. Tínhamos investido pouco nas ferramentas que poderiam ter facilitado tudo e pago as consequências.

Evitando desafios comuns da plataforma

Para aqueles que navegam pelas complexidades dos projetos de plataforma API, aqui estão minhas recomendações:

1. Abrace a padronização e a compatibilidade OpenAPI: O fascínio pelas soluções personalizadas é forte, mas os benefícios do alinhamento com ferramentas padronizadas e amplamente adotadas, como a OpenAPI, não podem ser exagerados. Essas estruturas oferecem um equilíbrio entre flexibilidade e estrutura, facilitando a adoção e a integração entre as equipes. Eles também reduzirão o tempo de integração para novas contratações à medida que sua equipe aumenta.
2. Concentre-se na experiência do desenvolvedor: Se você estiver construindo uma plataforma de API pública, a integração é receita. Se você estiver construindo uma arquitetura baseada em serviços, é assim que você obterá ganhos de eficiência. Concentre-se na redução das barreiras à integração. Crie ótimos SDKs para que os usuários possam integrar sem sair do IDE. Forneça ótimos documentos para que, caso eles saiam, possam encontrar facilmente as informações de que precisam.
3. Esteja atento à deriva: Esteja você usando uma DSL personalizada ou OpenAPI, a eficácia de todas as ferramentas que você cria é prejudicada pela precisão com que sua fonte de verdade reflete seu código. Se você estiver construindo uma nova API, há muitas estruturas de API (como FastAPI) que podem gerar uma especificação OpenAPI para evitar desvios. Se você já possui uma API, considere configurar algum monitoramento para verificar o tráfego ao vivo em relação ao que está documentado em suas especificações.
4. Invista na governança: Cultive um ambiente que priorize o design e a governança de APIs. Isso pode dar errado se você criar um conselho de governança de API, o que geralmente faz com que o desenvolvimento da API seja interrompido. Tente fornecer aos seus desenvolvedores ferramentas para verificar facilmente suas especificações com regras robustas de linting que verificam a consistência e a correção.

Se implementar estas recomendações parecer assustador, não se preocupe. Voltarei em algumas semanas com outro artigo. Enquanto isso, conecte-se comigo no LinkedIn e tire todas as suas dúvidas!

A postagem Por que os esforços da plataforma API não funcionam? apareceu primeiro em The New Stack.