Aprende algunos consejos sobre cómo crear tu API de manera eficiente y lidiar con el trabajo real simultáneamente.
Al crear una API para exponer una capacidad o integrar diferentes sistemas, hay principalmente dos formas de hacerlo: enfoque de Contrato-Primero o enfoque de Contrato-Último. La diferencia radica en la metodología que seguirás para crear la API.
En un enfoque de contrato-primero, la definición del contrato es el punto de partida. No importa qué lenguaje o tecnología estés utilizando. Esta realidad ha sido la misma desde el comienzo del sistema distribuido en tiempos de RMI y CORBA y continúa siendo la misma en los tiempos extraordinarios de gRPC y GraphQL.
Comienzas con la definición del contrato entre ambas partes: la que expone la capacidad y el consumidor inicial de la información. Eso implica la definición de varios aspectos de él:
- Propósito de las operaciones.
- Campos que tiene cada operación.
- Información de retorno dependiendo de cada escenario.
- Información de errores reportados, y así sucesivamente.
Después de eso, comenzarás a diseñar la API en sí y la implementación para cumplir con la definición acordada entre las partes.
Este enfoque tiene varias ventajas y desventajas, pero hoy en día es la forma más «aceptable» de desarrollar API. Como ventajas podemos comentar las siguientes:
- Reducción de Actividades de Retrabajo: Al comenzar definiendo el contrato, puedes validar rápidamente que todas las partes están de acuerdo con el contrato antes de escribir cualquier trabajo de implementación. Eso evitaría cualquier actividad de recodificación o retrabajo debido a un malentendido o simplemente adaptación de las expectativas y se volvería más eficiente.
- Separación de Funciones: También proporcionará la separación de funciones para ambas partes, el proveedor y los consumidores. Porque tan pronto como tengas el contrato, ambos equipos pueden comenzar a trabajar en eso. Incluso puedes proporcionar un simulacro para que el consumidor pruebe cualquier escenario rápidamente sin la necesidad de esperar a que se cree el servicio real.
Pero el enfoque de Contrato-Primero tiene algunos requisitos o suposiciones para tener éxito que no son muy fáciles de cumplir en un escenario del mundo real. Esta situación es esperada. Hay muchas metodologías, consejos o recomendaciones que aprendes cuando estás estudiando que no son aplicables en la vida real. Para validar ese comentario, permíteme hacerte una pregunta:
¿Creaste una API y la interfaz que creaste fue 100% la misma que tenías al final?
La respuesta a esa pregunta en mi caso es «No, nunca». Y puedes pensar que soy un mal diseñador de API, y podrías tener razón. Estoy seguro de que la mayoría de las personas que leen este artículo definirían sus contratos mucho mejor que yo, pero ese no es el punto. Porque cuando estamos en la fase de implementación, generalmente detectamos algo que no pensamos en la fase de diseño, o cuando intentamos hacer un diseño de bajo nivel, hay otros conceptos que no contemplamos en el punto que hace que otra solución sea la más adecuada para el escenario, por lo que impactarás la API, y eso tiene un costo.
Es posible que mitiges ese riesgo simplemente dedicando más tiempo a la fase de definición del contrato para asegurarte de que nada esté bien considerado o incluso crear algunos prototipos para garantizar que la API generada sea la final. Pero si haces esto, solo estás reduciendo la probabilidad de que esto suceda, nunca eliminándola, y al mismo tiempo, estás reduciendo los beneficios del enfoque.
Uno de los puntos críticos que comentamos anteriormente fue la eficiencia. Supongamos que pensamos en la eficiencia ahora cuando dedicarás más tiempo a esa fase. Eso significa que será menos eficiente. También comentamos sobre lo grandioso de hacer la separación de funciones: pero en este caso, mientras se extiende el tiempo de creación de la interfaz, también se extiende el tiempo que ambos equipos necesitan esperar hasta que puedan trabajar en sus partes.
Pero implementar el otro enfoque no proporcionará mucho beneficio. Puede llevar a un trabajo aún más costoso porque no obtendrás validación para el cliente hasta que la API esté implementada. Y nuevamente, otra pregunta:
¿Alguna vez compartiste algo con tu cliente por primera vez y no pidieron ningún cambio?
Nuevamente, la respuesta es la misma: «No, nunca». Y ese costo siempre será mayor que el que se habla del cambio en la definición, porque como sabes, el cambio es mucho más costoso cuanto más tarde lo detectes en el ciclo de desarrollo, y no es un aumento lineal. Es mucho más cercano a un aumento exponencial.
Entonces, ¿cuál es mi recomendación aquí? Sigue el enfoque de contrato-primero y acepta la vida real. Así que haz tu mejor esfuerzo para definir la API y tener un acuerdo entre las partes y si detectas algo que pueda impactar la API, notifícalo lo antes posible a las partes. Al final, esto no es más que un enfoque interactivo también para la definición de la API, y no hay nada de malo en ello.
Seamos honestos, no hay una bala de plata que proporcione el camino verde en tu trabajo diario, y eso es lo grandioso de hacerlo y por qué lo disfrutamos tanto. Porque en cada una de nuestras decisiones de trabajo, como sucede en cualquier otro aspecto de la vida, hay tantos aspectos, tantas situaciones, tantos detalles que siempre impactan la increíble y hermosa metodología que puedes ver en un artículo, un documento, una clase o un tweet.
