Diseñar una interfaz con la que puedas convivir
Consistencia antes que belleza
La misma convención de nombres en cada ruta, la misma estructura de respuesta, el mismo formato de fecha, la misma estructura de error. Diez rutas consistentes son más fáciles que cinco brillantes y cinco distintas.
Devuelve una estructura estable: un objeto envoltorio con datos y metadatos, para poder añadir campos sin romper.
Decisiones que vuelven a ti
Paginación. Decide de antemano — por posición o por cursor — y sopórtala en cada lista. Las listas sin paginación siempre crecen más de lo esperado.
Filtrado y orden. Definidos y documentados, no un campo libre en el que cada consumidor inventa reglas.
Identificadores. Estables, no secuenciales, y que no revelen información de negocio en su número.
Los errores son parte del contrato
Un código de estado correcto, un identificador de error fijo sobre el que ramificar la lógica, un mensaje legible, y un identificador de petición para investigar. Una interfaz que devuelve texto libre distinto en cada error obliga al consumidor a comprobar cadenas.
En profundidad
Documenta la interfaz desde el propio código para que la documentación no envejezca, y ofrece un entorno de prueba con datos ficticios. Y antes de publicar: que alguien que no escribió la interfaz implemente un escenario completo contra ella; cada pregunta que haga es un defecto de diseño, no una laguna de su entendimiento.