¿API REST? Seguro?

09 oct 2026

El problema

Hace unos meses, me hice cargo de un micro-servicio para desarrollar nuevas características.

Lo primero que hice fue revisar el código. Supuestamente, este micro-servicio gestiona y sirve un recurso llamado persona a través de un API REST. Y me encontré esto:

/personas/datosPersona, /personas/datosPersonaBasica, /personas/datosCrearPersona, /personas/datosPersonaModificarIdentificaciones, /personas/datosPersonaBuscar

¿De verdad? Esto es la supuesta primera versión del API REST. Y también me encontré esto:

/personas/informarPersona, /personas/informarPersonaBasica, /personas/informarNuevaPersona, /personas/informarBuscaPersona, /personas/informarModificarPersona

Estos endpoints son la segunda versión del API REST.

Todos los endpoints utilizan el verbo HTTP POST.

Esto es una locura. El recurso es persona pero por los nombres de los endpoints parece que hay un montón de recursos: datosPersona, datosPersonaBasica, datosCrearPersona, datosPersonaModificarIdentificaciones, datosPersonaBuscar, etc.

Los endpoints deben llamarse según el recurso que representan:

/persona

Sí, estoy de acuerdo, no existe un estándar de API REST definido por la IETF, pero existe un estándar de facto y existe un consenso general sobre los patrones que se deben aplicar para cada caso de uso que los micro-servicios deben seguir.

El verbo HTTP es importante

Todos los endpoints mostrados anteriormente, comparten una característica común, el verbo HTTP usado es siempre el mismo: POST

Esto es un error, ya que el verbo HTTP está ligado a un significado concreto:

  • POST Usado para operaciones de creación
  • PUT Usado para operaciones de sustitución
  • PATCH Usado para operaciones de actualización
  • DELETE Usado para operaciones de borrado
  • GET Usado para operaciones de lectura o de búsqueda

Por lo tanto, un POST a un endpoint /persona significa la creación de un nuevo recurso persona. Un GET a un endpoint /persona significa una lectura o una búsqueda, depende de los parámetros.

Parámetros

Hay diversas maneras de indicar parámetros a un endpoint:

  • path argumentos, como /persona/{idPersona}
  • query argumentos, como /persona?m=b
  • body argumentos, como objetos JSON

Cada manera, combinada con el endpoint y el verbo HTTP implica diferentes acciones.

  • path se utilizan para lecturas basadas en claves como el ID de una persona
  • query se utilizan para definir los parámetros de búsqueda o para determinar aspectos de las operaciones de lectura
  • body se utilizan para indicar los datos en operaciones de creación, sustitución y actualización

Modelos dinámicos para lectura y búsqueda

En algunos casos, sobre todo si el modelo es muy pesado, el usuario puede querer reducir el número de propiedades del modelo a obtener.

Esto se puede conseguir con parámetros query que especifiquen que partes del modelo se desea obtener.

Estas partes deben ser predefinidas y documentadas en el REST API.

En cualquier caso, debe existir un grupo de propiedades básicas que siempre se obtienen, por ejemplo el ID.

Para reducir al máximo la medida de la petición HTTP, el parámetro y los argumentos deben ser reducidos a la mínima expresión. Yo prefiero utilizar un parámetro query llamado m, por modelo.

Los valores de este parámetro serán letras que estarán asociadas a un conjunto de propiedades del modelo

Estos valores pueden combinarse para que el usuario pueda determinar las partes del modelo que quiere obtener.

Por ejemplo, en el caso del recurso persona:

  • r personas relacionadas
  • e información económica
  • c información de contactos (como email, teléfono, direcciones postales, etc.)
  • g información de gestiones

Por lo tanto, si el usuario quiere obtener las personas relacionadas y los datos de contacto, la llamada HTTP será:

GET /persona/<idPersona>?m=rc

En los casos de búsqueda, se deberá combinar el parámetro de modelo con los parámetros de búsqueda:

GET /persona?f="e=>50"&m=rc&p=1&s=25

Esta llamada debe interpretarse como:

  • f Indica el filtro: edad igual o mayor que 50
  • m El modelo a obtener contendrá (además de las propiedades básicas) personas relacionadas y datos de contacto
  • p Página primera (comienza en 1)
  • s Medida de la página es 25 (s por la palabra Inglesa «size»)

Versionado del REST API

Esta es una parte esencial de REST API. De la misma manera que el software tiene versión, el REST API que implementa también debe tener versión.

El sistema para establecer la versión varia:

  • Versionado con el path
  • Versionado con header HTTP específico
  • Versionado con el Media Type
  • Versionado con parámetros query

El versionado con el path se consigue añadiendo un prefijo:

/api/v1/persona

Personalmente prefiero el método de header HTTP específico. Yo utilizo un header llamado x-api-version.

Así, en el caso expuesto antes, el mismo endpoint sirve las dos versiones del API.

Por lo tanto, los endpoints para la misma operación de las dos versiones: /personas/datosPersona y /personas/informarPersona utilizarían el mismo endpoint: /persona y la diferencia la marcaría únicamente el header.

¿Como expresar la versión? Existe una costumbre generalizada de utilizar una letra uve y un número: v1. Podemos utilizar, también, solo el número. En cualquier caso, el número debe coincidir con la versión mayor del software que lo implementa (recordemos el versionado semántico)

Distribución de versiones

¿De qué manera pueden coexistir dos versiones del mismo REST API? Bueno, esto depende de la manera en que esté implementado:

  • Dos instancias diferentes del mismo servicio para diferentes versiones (1 y 2)
  • La misma instancia implementa las dos versiones

La solución depende del entorno de ejecución. Si el sistema de orquestración soporta la ejecución de dos instancias diferentes asociadas con el mismo servicio, con opción para filtrar el enrutamiento por el contenido del header HTTP, esta sería la mejor opción, ya que el código sería limpio y fácil de mantener. Si no, la única solución sería implementar las dos versiones en el mismo código, pero este método requiere un diseño, codificación, gestión y mantenimiento muy cuidadoso.