No post anterior, recomendamos prototipar UX para explicitar a linguagem onipresente de um domínio. Entretanto, por entendermos que UX é muito mais do que as “telinhas” de um sistema, continuamos nesse tema.

Nesse post, trataremos sobre como usar protótipos de UX para explicitar a linguagem onipresente de um domínio em projetos de API.

Dê ênfase ao código consumidor…

[tweet]Quando for escrever uma API, também escreva código para consumir essa API.[/tweet]

Uma API bem projetada é centrada no propósito do código consumidor. Em nossa experiência, não seguir essa ideia causa erros de implementação e dificuldades de entendimento.

Na ExímiaCo, orientamos a escrita do código que consome a API antes mesmo de escrever a API. Esse simples exercício amplia o entendimento do domínio e resulta em design enxuto e eficiente.

Importante destacar que, como indicado por Ronnie Mitra (autoridade no desenvolvimento de APIs), escrever testes de unidade não é suficiente. Afinal, temos que escrever código que demonstre que seguimos perspectiva do cliente e não uma especificação.

São os códigos que consomem uma API que realizam o propósito do domínio. Esses códigos conseguem demonstrar se as  expressões e nomes escolhidos para a linguagem onipresente são ou não adequadas.

… mas não pare no “código”

Se o propósito de uma API for fornecer dados e comportamento para determinados tipos de interface, nós, da EximiaCo, recomendamos prototipar  e até mesmo implementar esses tipos de interface para que o código consumidor que estamos emulando seja ainda mais fiel.

Feedback é princípio fundamental para agilidade. Se um único componente de interface precisar fazer chamadas para duas APIs distintas para ser renderizado, então, esse protótipo estará gritando que os “contextos” não foram identificados corretamente.  

Em nossas consultorias temos encontrado APIs restlike, com recursos com belos nomes, mas desconectados do uso, que têm causado sobrecarga de rede, além de serialização e materialização de objetos grandes (onerando o GC).

Como regra geral, identificamos que se a UX, para renderizar um único componente, precisa recorrer a composição de dados (seja server-side ou client-side), temos indícios de modelagem anêmica.

É no código que consome uma API que a linguagem onipresente do domínio irá se refinar e emergir naturalmente.

Software funcionando mais do que documentação abrangente

Entendemos e defendemos que a geração de documentos é essencial para o desenvolvimento de software. Sobretudo, quando os riscos envolvidos forem grandes.

De qualquer forma, quando comparamos glossários a protótipos de interface, entendemos que os protótipos estão muito mais próximos de software funcionando do que uma lista fria de termos e significados. Por isso, entendemos que protótipos são ferramentas mais adequadas para explicitar a linguagem de domínio, enquanto o glossário é documento resultante (nem fim, nem meio).

Consolidando

Ao projetar uma API, simule o uso através de código cliente e, se houver uma interface com usuário envolvida, simule também essa interface.

Pessoas são, com frequência, visuais. Protótipos de interface ou até mesmo do código consumidor ajuda a tornar mais tangíveis os conceitos do domínio.

Desenvolvimento de software é um processo iterativo. Embora reuniões iniciais sirvam para definir alguns poucos conceitos, antes dos primeiros protótipos e interações, será a partir do processo cíclico que a linguagem irá emergir. 

Obviamente, os protótipos são elaborados de forma iterativa e interativa, sempre envolvendo os especialistas. No final, os protótipos acabam até permitindo a escrita de documentos textuais descritivos, entretanto, com indicativos de menor ambiguidade.