Número 11
11 de maio de 2022

Apicade as vosas APIs

Un día estaba eu a tentar empregar un servizo RPC e non o estaba a pasar moi ben. Para facer calquera cousa tiña que chamar a varias funcións cunha morea de argumentos; algúns deses argumentos eran obrigatorios pero innecesarios e outros tiñan distintos significados dependendo do que quixera facer.

O servizo non era consistente na xestión dos erros: algunhas funcións botaban unha excepción, pero outras respondían cun obxecto que tiña un campo “erro”. O servizo tiña unha biblioteca cliente pero usaba variables globais, así que ás veces tiña que gardar o valor antigo da variable para podelo restaurar despois.

En definitiva: era un desastre.

Dous homes operando un modelo de bicicleta moi estrafalario.

Os servizos RPC, igual que as bibliotecas de código, teñen unha interface. Non é unha interface de usuario na que unha persoa usa fiestras ou unha terminal ou un navegador para usar un programa, senón que é unha interface de programador. Nesta interface, o programador fai chamadas a funcións para usar o servizo. Esta interface é o que chamamos unha “API”.

É difícil deseñar unha boa API. É, a ben seguro, máis difícil que programar o servizo que expón esa API: dá igual se o código do servizo é bo ou malo, se está feito en Rust ou en Python, se usa algoritmos O(log n) ou O(2ⁿ), ou se en realidade non hai ningún programa senón que son tres paisanos nun pendello de Esteiro recibindo as peticións RPC por fax e mandando as respostas por carta; con tal de que o servizo funcione, xa vale.

En cambio, a API non ten unha implementación invisible: é o que é; se está mal deseñada, o usuario ha notalo inmediatamente e ha sufrir.

Polo tanto, se non tedes experiencia deseñando APIs e estades a facer un servizo ou unha biblioteca ou algo que expoña unha API, é bastante probable que saia bastante mal. É evidencia diso o número de proxectos en GitHub nos que a versión 1 tiña unha API tan mala que a API da versión 2 é completamente distinta.

Por desgraza, o deseño de APIs é outra desas cousas que non nos aprenden, así que, polo momento, a única maneira de aprender a deseñar APIs é… en fin, é deseñar APIs. Vaia leria.

Se tedes sorte, podedes colaborar con alguén que xa teña experiencia e que vos revise o deseño para dicirvos “esta si, esta non, esta góstame, etc”. Se sabedes de ninguén, hai unha alternativa: escribide un ou dous programas que usen a API. Desta maneira poderedes experimentar a vosa API en primeira persoa e poderedes notar que partes son boas e que partes son malas, que é difícil de facer e que é doado, etc.

Se non sabedes que programa escribir, hai unha solución moi simple: usade os vosos tests unitarios! (Tedes tests unitarios, non?) Xa que os tests proban toda a funcionalidade do voso servizo, non debería ser moi difícil usar toda a API neles.

Eu acho que é un método moi efectivo: moitas veces vexo que o código dos tests é moi difícil de escribir ou entender así que fago algúns cambios na API e, de súpeto, os tests fanse máis curtos e sinxelos.

Non pensedes que vos librades deste problema se nunca escribides servizos RPC ou bibliotecas de código, porque non todas as APIs son externas. As funcións e clases do voso programa forman unha API interna, e tamén tedes que asegurarvos de que esa API interna estea ben deseñada, ou o código do voso programa ha ser innecesariamente longo e difícil de entender.

A ilustración desta Folla procede de “Cycling Art, Energy, and Locomotion”.