APIs não são uma novidade, embora muito esteja se falando delas nos últimos anos. A sigla API, significando Application Programming Interface entrou em uso geral quando a Microsoft publicou a documentação das APIs do Windows. Isso foi lá pelos idos de 1990, ou até antes.

Comecei a me envolver com o desenvolvimento para Windows quando a plataforma ainda era jovem (e eu um adolescente) e por isso desde cedo me acostumei a lidar com APIs. Com o passar do tempo as ferramentas de desenvolvimento introduziram frameworks que mais e mais isolavam o desenvolvedor das APIs que estavam por trás do que faziam, mas quem as conhecia estava sempre pronto a recorrer a uma para fazer algo que era impossível apenas com o framework da linguagem em questão.

Com o advento da Internet surgiram novas formas de se criar e publicar APIs. Ao invés de serem DLLs que estavam instaladas em seu computador as APIs passaram a ser serviços que estavam disponíveis em servidores na Web. A primeira vez que projetei uma API para ser chamada via Web, nós a chamamos de adaptador HTTP.

Lembro-me como se fosse ontem (era 1998). Naquele momento não estávamos preocupados em inventar nomes para nossa forma de trabalho. Estavamos apenas criando uma forma de um serviço que tínhamos criado para mandar mensagens para o sistema bancário de um grande banco estatal e que pudesse ser chamado a partir de uma aplicação que ficava instalada nas máquinas dos usuários. Tínhamos acabado de implementar um servidor para EDI (Electronic Data Interchange) e passado por muitas dores para estabilizá-lo e garantir que não tinha memory-leaks. Não queríamos criar o código que serviria como servidor de aplicação então resolvemos utilizar o servidor Web para fazer este papel para nós.

Hoje, utilizar um servidor Web para disponibilizar serviços parece a coisa mais óbvia do mundo (e é), mas naquela época ainda era uma coisa pouco usual.

Todo o trabalho que fizemos nas aplicações que compunham este projeto foi baseado na criação de APIs e subsequentemente das aplicações que as consumiriam. Estas eram o que chamamos hoje de APIs internas. Mesmo quando disponibilizamos acesso aos serviços via HTTP e EDI, estes eram consumidos por aplicações criadas pelo próprio banco.

Naquela época a criação de APIs abertas ainda era o domínio de poucos. Apenas as grandes empresas de tecnologia como Microsoft, Novell, IBM, etc publicavam APIs para uso de meros mortais.

Este é um ponto que a utilização de APIs mudou bastante. O custo da infraestrutura impedia que muitas empresas pequenas tivessem condição de oferecer serviços. Com a redução brutal do custo da infraestrutura e a explosão de pequenas empresas criando APIs para que seus serviços possam ser integrados com outros, o conceito se popularizou.

Para que aplicações tenham boa manutenabilidade (capacidade de dar-se manutenção) é importante que ela seja baseada em APIs (no mínimo, APIs internas à aplicação). Uma vez que você tenha definido a API e a implementado pode construir a interface da mesma, utilizando as suas próprias funcionalidades.

Isto tem alguns benefícios: contribui para que seu código esteja fazendo sentido e organizado; permite a identificação de funções que estão faltando no serviço quando não se consegue implementar a interface desejada e garante que tanto a interface quanto chamadas feitas por outros sistemas estejam utilizando o mesmo código. Utilizar o mesmo código para processar interação humana e sistêmica garante consistência de comportamento e torna a manutenção da aplicação mais fácil.

Comece sempre a pensar em qualquer aplicação que vá construir, pela sua API. De fato, a melhor forma de começar pode ser documentando a API que vai criar, antes mesmo de escrever uma única linha de código.

Sei que documentação tem uma má fama entre os desenvolvedores e peço que creiam em mim quando digo que não sou mais fã do que qualquer um de vocês de processos que exigem a criação de montanhas de papel (mesmo que seja virtual). Quando falo em documentar a API, me refiro a um documento que listas as funcionalidades, seus parâmetros de entrada e saída e qualquer informação que seria importante para outro desenvolvedor do seu time saber utilizar a funcionalidade.

Compartilhe este documento com seus colegas e peça que indiquem se acham que alguma coisa está faltando (provavelmente estará). Tenham sempre em mente que a única forma de realmente validar se a API está realmente completa é implementar a sua aplicação utilizando-a como base.

Em um mundo que está sempre em mudança, suas APIs provavelmente nunca estarão realmente completas. O mais importante e ter sempre em mente que uma API que você torna pública é como um contrato que assina. Não pode voltar atrás e mudar os termos. Da mesma forma uma API não deve ser modificada e sim estendida.

Mudar uma API implica em “quebrar” as aplicações que já a utilizam.  Isso deve ser evitado ao máximo.  As consequências de uma mudança deste tipo para os seus clientes serão aplicações “quebradas” e usuários estressados.  Isto leva a uma perda de confiança no seu serviço e consequentemente na sua empresa.

Mauricio Longo Consultor, escritor e palestrante com atuação internacional. Autor de mais de 15 livros sobre desenvolvimento de software e sistemas operacionais. Participou do startup de diversas empresas e apóia projetos open source. LinkedIn: http://www.linkedin.com/in/mauriciolongo Twitter: @mauriciolongo e @mauricioblongo