Versionado de APIs

¿Por qué es difícil mantener APIs estables?

Requisitos cambiantes del negocio
Evolución tecnológica
Errores de diseño inicial
Expectativas de los consumidores
Escalabilidad y rendimiento
Compatibilidad retroactiva
Falta de gobernanza y documentación
Cambios en regulaciones o estándares

Mejores prácticas de versionado de APIs con Spring Boot

Versiona en el contrato usando rutas o encabezados de petición

@RestController
@RequestMapping("/api/v1/users")
class UserControllerV1 {
  @GetMapping("/{id}") public UserV1 get(@PathVariable Long id) { ... }
}
@RestController
@RequestMapping("/api/v2/users")
class UserControllerV2 {
  @GetMapping("/{id}") public UserV2 get(@PathVariable Long id) { ... }
}

Ejemplo usando rutas

@RestController
@RequestMapping("/api")
class UsersController {
  private final UsersService service;

  @GetMapping(value="/users/{id}", produces={
      "application/json", 
      "application/vnd.acme.user.v2+json", 
      "application/vnd.acme.user.v1+json"
  })
  public ResponseEntity<?> getUser(
      @PathVariable Long id,
      @RequestHeader(value="version", required=false) String version) {

    var user = service.find(id).orElseThrow(() -> new EntityNotFoundException("User " + id));
    if (version != null && version.contains("v-1")) {
      return ResponseEntity.ok(toV1(user));
    }
    return ResponseEntity.ok(toV2(user)); // default behaviour
  }
}

Ejemplo usando encabezados

Cambios solo aditivos en versiones menores

Añade campos, no elimines ni cambies semánticos. Si necesitas romper, sube a v2.

Desacopla modelos internos de DTOs públicos

Nunca expongas entidades JPA. Mapea con MapStruct o tu servicio favorito, y mantén DTOs por versión si hace falta: UserV1, UserV2.

record UserDto(
	Long id, 
	String email, 
	@JsonInclude(JsonInclude.Include.NON_NULL) 
	String nickname) {

}

Cabeceras de deprecación

Anuncia deprecaciones programáticamente

@Component
class DeprecationHeaderFilter implements Filter {

  @Override public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
      throws IOException, ServletException {
    HttpServletResponse http = (HttpServletResponse) res;
    chain.doFilter(req, res);
    if (((HttpServletRequest) req).getRequestURI().startsWith("/api/v1/")) {
      http.addHeader("Deprecation", "true");
      http.addHeader("Sunset", "2026-06-30T00:00:00Z");
      http.addHeader("Link", "</api/v2/users>; rel=\"successor-version\"");
    }
  }
}

Errores estables con RFC 7807

Usa ProblemDetail (Spring 6+) para respuestas de error predecibles.

@RestControllerAdvice
class GlobalErrors {

  @ExceptionHandler(EntityNotFoundException.class)
  ResponseEntity<ProblemDetail> notFound(EntityNotFoundException ex) {
    var pd = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);
    pd.setTitle("User not found");
    pd.setDetail(ex.getMessage());
    pd.setProperty("error_code", "USER_404");
    return ResponseEntity.status(HttpStatus.NOT_FOUND).body(pd);
  }
}

Validación consistente

No aceptes basura y luego culpes al cliente.

record CreateUserReq(
  @NotBlank String email,
  @Size(max=50) String name
) {}


class UserController{

	@PostMapping
	ResponseEntity<UserDto> create(@Valid @RequestBody CreateUserReq req) {
	// Business logic here
	}

}

Tácticas de evolución seguras

Tolerancia a campos desconocidos

Que tu servidor y cliente no exploten si aparecen campos nuevos.

@JsonIgnoreProperties(ignoreUnknown = true)
record ClientRequest(
  String name,
  String lastName,
  Double balance,
  ...) {}

Paginación estable y cursors

Evita ordenar por campos inestables. Usa createdAt o IDs monotónicos. Expón nextCursor en vez de page=123 si el volumen es grande.

@Entity
@Table(name = "users")
class User {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    private String email;

    @Column(nullable = false, updatable = false)
    private Instant createdAt;

    @PrePersist
    void prePersist() {
        this.createdAt = Instant.now();
    }

    // getters y setters
}

Usando id monotónico como cursor

Si tus IDs crecen de forma predecible (ej. AUTO_INCREMENT o IDENTITY), puedes usarlos para paginación estable.

public interface UserRepository extends JpaRepository<User, Long> {

    // Dame los usuarios con id mayor que el cursor
    List<User> findTop10ByIdGreaterThanOrderByIdAsc(Long cursor);
}

record PageResponse<T>(List<T> data, Object nextCursor) {}

@GetMapping
public PageResponse<UserDto> getUsers(@RequestParam(required = false) Long cursor) {
    var users = repo.findTop10ByIdGreaterThanOrderByIdAsc(cursor == null ? 0L : cursor);
    Long next = users.isEmpty() ? null : users.get(users.size() - 1).getId();
    return new PageResponse<>(users.stream().map(UserDto::from).toList(), next);
}

Patrón general de respuesta con cursor

Idempotencia

Para POST sensibles, soporta Idempotency-Key para que los reintentos no creen duplicados. Menos sorpresas, menos tickets.

@Component
class IdempotencyFilter extends OncePerRequestFilter {

    @Override
  protected boolean shouldNotFilter(HttpServletRequest request) {
    // Sólo aplica a POST (o PUT) de endpoints que lo requieran
    return !("POST".equalsIgnoreCase(request.getMethod()) &&
             request.getRequestURI().startsWith("/api/orders"));
  }

  @Override
  protected void doFilterInternal(HttpServletRequest req, HttpServletResponse res, FilterChain chain)
      throws IOException, ServletException {

    // logica para determinar si filtramos la petición
    try {
      chain.doFilter(requestWrapper, responseWrapper); // ejecuta el controlador
    } finally {
      // Guardar respuesta
      rec.status = responseWrapper.getStatus();
      rec.body = new String(responseWrapper.getContentAsByteArray(), java.nio.charset.StandardCharsets.UTF_8);
      // guarda headers interesantes
      Map<String,String> headers = new HashMap<>();
      var location = responseWrapper.getHeader("Location");
      if (location != null) headers.put("Location", location);
      rec.headersJson = new com.fasterxml.jackson.databind.ObjectMapper().writeValueAsString(headers);
      rec.completed = true;
      repo.save(rec);

      // Copiar el body al response real
      responseWrapper.copyBodyToResponse();
      res.setHeader("Idempotency-Key", key);
    }
  }
}

ETags y control de cambios

Respuestas con ETag + If-None-Match para caching y actualizaciones condicionales. No es glamuroso, pero evita lecturas inconsistentes sin tener que romper endpoints.

Contrato primero y documentación

OpenAPI como fuente de verdad

Genera documentación con springdoc-openapi y publícala.
• Congela el contrato en PRs y bloquea rupturas con openapi-diff en CI.

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.6.0</version>
</dependency>

Contract tests (consumer‑driven)

Usa Spring Cloud Contract para verificar que sigues cumpliendo lo prometido a clientes.

Productor: publica stubs.
Consumidor: verifica que el stub sigue valiendo antes de que tú “optimices” algo y rompas medio ecosistema.

Golden tests de JSON

Prueba payloads con JsonContent y snapshots.

@WebMvcTest(UserControllerV1.class)
class UserV1JsonTest {
  @Autowired JacksonTester<UserV1> json;

  @Test void shapeIsStable() throws Exception {
    var u = new UserV1(1L, "a@b.com", null);
    assertThat(json.write(u)).isStrictlyEqualToJson("expected/user-v1.json");
  }
}

Infraestructura y herramientas útiles

Spring Gateway para versionado y rutas

Spring Cloud Gateway puede rutear /v1/** a un backend y /v2/** a otro.

También añade y traduce encabezados de compatibilidad. Ideal cuando quieres matar v. 1 sin cirugía mayor.

OpenAPI-diff

Analiza las diferencias entre dos especificaciones (v.3)

Migraciones de esquema controladas

Flyway/Liquibase con el patrón “expand/contract”: primero añade columnas nuevas, luego escribe doble, después migra lecturas, y al final limpia lo viejo. Tu API ni se entera.

<dependencies>
    ...
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-core</artifactId>
    </dependency>
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId> 
        <scope>runtime</scope>
    </dependency>
    <dependency>
        <groupId>org.flywaydb</groupId>
        <artifactId>flyway-database-postgresql</artifactId> 
        <scope>runtime</scope>
    </dependency>
</dependencies>

Ejemplo con Flyway

create sequence task_seq increment by 50;

create table task
(
    task_id       bigint                   not null,
    username      varchar(255)                     ,
    description   varchar(255)             not null,
    creation_date timestamp with time zone not null,
    due_date      date,
    primary key (task_id)
);

Las migraciones versionadas siempre empiezan con la letra V, en mayúscula

Ejemplo:

src/main/resources/db/migration/V1__create_task.sql

ALTER TABLE task ADD COLUMN full_name VARCHAR(255);

Actualizamos la tabla agregando campos sin borrar los antiguos

Ejemplo:

src/main/resources/db/migration/V2__alter_task.sql

UPDATE task SET full_name = username;

Las migraciones versionadas siempre empiezan con la letra V, en mayúscula

Ejemplo:

src/main/resources/db/migration/V3__update_task.sql

ALTER TABLE task DROP COLUMN username;

Las migraciones versionadas siempre empiezan con la letra V, en mayúscula

Ejemplo:

src/main/resources/db/migration/V4__alter_task.sql

Reglas generales para no romper una API

No renombres campos ni cambies tipos en una versión; añade nuevos y documenta.
No reutilices códigos de error con significados distintos.
Documenta la ventana y plan de eliminación de endpoints obsoletos.
Automatiza chequeos de contrato en CI. Si no está en CI, no existe.
Mantén ejemplos de requests/responses y actualízalos en la doc. Los clientes los copian sin leer, asúmelo.

Versionado de APIs

¿Por qué es difícil mantener APIs estables?

Mejores prácticas de versionado de APIs con Spring Boot

Versiona en el contrato usando rutas o encabezados de petición

Cambios solo aditivos en versiones menores

Desacopla modelos internos de DTOs públicos

Cabeceras de deprecación

Errores estables con RFC 7807

Validación consistente

Tácticas de evolución seguras

Tolerancia a campos desconocidos

Paginación estable y cursors

Usando id monotónico como cursor

Patrón general de respuesta con cursor

Idempotencia

ETags y control de cambios

Contrato primero y documentación

OpenAPI como fuente de verdad

Contract tests (consumer‑driven)

Golden tests de JSON

Infraestructura y herramientas útiles

Spring Gateway para versionado y rutas

OpenAPI-diff

Migraciones de esquema controladas

Ejemplo con Flyway

Reglas generales para no romper una API

Versionado de APIs

More from Anyul Led Rivas