Ergonomia de API’s empresariais

Olá, esta é a primeira vez que estou escrevendo um artigo para o blog, então deixe-me apresentar.
Trabalho a 12 anos com desenvolvimento de software, destes 12, 10 dedicados a Java e J2ee com os frameworks mais diversos.
Também trabalhei bastante com PHP e Javascript, e outras “aventuras” que sempre agregaram muito a minha carreira.

Sejam bem vindos, e boa leitura.

– Introdução

Ao participar de vários projetos de desenvolvimento, onde minha equipe precisava trabalhar ou disponibilizar rotinas e padrões, percebemos dificuldades nos dois lados.
Pessoas na equipe com conhecimento limitado e que não utilizavam inglês técnico.
Funções disponibilizadas pela empresa em bibliotecas internas, que já existiam na própria linguagem nativa, entre outros exemplos.
Sendo assim, ao analisar os fatos, se deparamos com o paradigma de criação e reutilização de código.
Assim, uma das boas práticas de desenvolvimento de software(eu diria a mais importante), é a própria reutilização de código.

Escrever a mesma coisa, ou “reinventar a roda” são problemas comuns do dia a dia dos desenvolvedores, e causam grande retrabalho e perda de tempo (time is money).
Para resolver este problema, utilizamos as chamadas API’s. Mas o que é uma API?

– O que diabos é uma API?

API, é a sigla de Application Programming Interface, na tradução livre, Interface de Programação de Aplicativos. Não é só isto.
Uma definição que criei para API é:
Uma API é uma interface que engloba e disponibiliza rotinas e padrões de um software, que serão utilizados por desenvolvedores em sistemas externos, sem terem a necessidade de conhecer detalhes técnicos da implementação e do código da API em questão.

– Por onde começar?

Da mesma maneira que os desenvolvedores utilizam diversas API’s, eles podem também escrever API’s.
Como você não gostaria de utilizar uma API mal escrita e mal documentada, o desenvolvedor que for utilizar sua API tem o mesmo sentimento.
Isso me remete a uma antiga frase, não sei de quem é a autoria: “Programe como se o programador que for utilizar seu código é um serial killer que sabe onde você mora”.
Faça a coisa direito.

– Como escrever uma boa API?

Eu entendo que a construção de uma boa API deve ter 3 premissas: facilidade (de usar), simplicidade (fazer muito com pouco) e documentação.
Seguindo estas premissas e as características a seguir, sua API vai ser utilizada sem dar dor de cabeça para os desenvolvedores.
É o famoso “RTFM” (leia o maldito manual).

– Características de uma boa API

* Fácil de usar, mesmo sem documentação
Se ela for fácil de usar, com nomes de pacotes, classes, métodos e variáveis intuitivos, o desenvolvedor sequer vai precisar recorrer a documentação. E isto é um bom sinal.

* Não permitir má utilização
Não permitir que o desenvolvedor faça mal uso da API. Controlar os parâmetros e valores de entrada, lançando exceções claras, vai lhe poupar tempo. Como regra deixe acessível ao desenvolvedor somente o que for estritamente necessário da API. Utilize as boas práticas da segurança dentro da orientação a objetos.

* Fácil de entender e manter o código que utiliza ela
Sua API pode não salvar o mundo, então permita que os desenvolvedores possam utilizar suas rotinas, extendendo ou implementando suas interfaces, para suprirem suas necessidades.

* Robusta o suficiente para atender os requisitos
De nada adianta uma API maravilhosamente escrita, se ela não atende os requisitos a qual se propõe, ou também, se é uma reinvenção da roda.

* Fácil de testar
Desacople sua API o suficiente, dentro dos limites da segurança, para que partes dela possam ser utilizadas em rotinas de testes unitários dos sistemas que as utilizam, auxiliando assim nos testes dos sistemas externos.

– Últimas considerações e dicas

* Estas regras não valem apenas para API’s escritas para ser utilizadas por desenvolvedores internos (da mesma empresa ou projeto), utilize estas técnicas ao escrever um WebService por exemplo, que não deixa de ser uma API externalizada.

* Nomes de métodos SEMPRE totalmente em português, jamais misture português com inglês. Salvas exeções em que no projeto trabalhem pessoas de diferentes nacionalidades e línguas, então o padrão é utilizar inglês. Mesma coisa para quando você escreve uma API para o mercado, o padrão é inglês.
Se sua empresa for vendida para uma empresa de outro país, acredite, eles terão muito mais trabalho para fazer do que pensar em reescrever nomes de métodos de português para inglês.

– Conclusão

Com ações simples podemos salvar muito tempo.
Escrever e utilizar API’s da forma correta, fará com que os desenvolvedores economizem tempo em manutenção ou implementações futuras.
Lembre-se, o seu código está sempre sujeito a modificações devido a “variáveis” externas.
Jamais espere que sua API ou implementação nunca precisará de manutenção. A melhor dica é, siga estas recomendações e prepare-se para gastar menos tempo.
Outra importante dica. Quanto melhor sua API, mais desenvolvedores vão utiliza-las, e mais difícil (ou quase impossíveis) serão as alterações nela.
Por isso o desaclopamento da API é importante.
Concluindo, projete as API’s como você as fosse utilizar.