Versionado
Qué puede cambiar bajo tus pies, y qué no.
La versión está en la ruta: /api/v1/....
Los cambios aditivos entran en la v1. Un campo nuevo en una respuesta, un parámetro opcional nuevo, una ruta nueva, un permiso nuevo. Escribe clientes que ignoren los campos que no conocen, porque aparecerán campos nuevos.
Cualquier cosa que quite un campo o cambie su significado espera a la v2. Las
dos correrían lado a lado mientras la v1 se descontinúa, con una cabecera
Deprecation y una fecha de cierre anunciada antes de que cualquiera de las dos
signifique algo.
Una excepción
Una vez, en octubre de 2026, la v1 perdió campos sin esperar a la v2. Los
colores que guardaba el layout de Profile Studio salieron de las respuestas de
GET /api/v1/profile/layout y GET /api/v1/profiles/{username}/layout:
color en un background (el de la página, el de una sección o el del
style de un bloque), textColor en el style de un bloque y color,
background y radius en un elemento text. Habían llegado con el schema
2 del layout el 12 de octubre de 2026, a las 06:10 UTC, y salieron el mismo
día, cuando el texto y los fondos pasaron a seguir siempre el tema.
La regla se dejó de lado esta vez porque esos campos estuvieron menos de un
día en producción. El schema sigue siendo 2. Un PUT que todavía los
envía no se rechaza: se descartan y el resto se guarda. Un background que
solo tenía color pasa a null, y tone auto, que miraba el color, ahora
mira solo la imagen.
La regla sigue en pie: cualquier otra eliminación espera a la v2.
Qué no es contrato
- El
messagede un error. Compara por elcode. - El orden de las claves en un objeto.
- La redacción exacta de cualquier cosa escrita para que la lea una persona.
Las rutas del propio sitio
Hay dos docenas de handlers bajo /api que no son esta API. Son los del sitio,
moldeados alrededor de una pantalla cada uno, y cambian cuando esa pantalla
cambia. Ninguno acepta una llave, así que nada pasa a depender de ellos por
accidente.