Creación de la API de datos v2 en Webflow: Parte 1

Entre 2015 y 2016, nuestro equipo lanzó la API REST de Webflow, la cual se centraba en los creadores web de los sectores del mercado donde Webflow estaba siendo ampliamente adoptado.

Inicialmente, la API permitía a los desarrolladores externos consultar el CMS de Webflow y responder a eventos del sitio (por ejemplo, envíos de formularios). Con el tiempo, la superficie de la API siguió expandiéndose a medida que añadíamos funciones y atendíamos nuevas solicitudes de los desarrolladores.

Dentro de nuestro departamento de ingeniería, esto significaba que más equipos de producto contribuían al código base y a las API asociadas. Sin embargo, a medida que la superficie de la API seguía creciendo y llegaban más solicitudes de clientes, la API comenzó a fragmentarse.

Webflow crecía rápidamente, los desarrolladores externos querían integrarse en nuestra plataforma y algunos estaban construyendo todo su negocio creando aplicaciones que se conectaban a nuestras API millones de veces al día. Pero para alcanzar este nivel de éxito, los desarrolladores tenían que lidiar con una confusa variedad de formatos de respuesta de error y cargas útiles de webhooks.

Mientras planeábamos nuestra siguiente fase de mejoras, comenzamos reflexionando sobre qué debíamos hacer de forma diferente.

Identificamos tres áreas principales de mejora:

1. Consistencia, utilizando códigos de respuesta no estándar y plagada de comportamientos sorprendentes (por ejemplo, tener que pasar id: null para configurar propiedades de SKU).
2. Uso de un modelo de estilo y gobernanza. Incluso si limpiábamos la API en su estado actual, no teníamos un mecanismo para evitar una mayor dispersión y fragmentación.
3. Permisos granulares que requerían que los usuarios otorgaran autorización total a su sitio. Un obstáculo insalvable para muchos de nuestros clientes empresariales.

A principios de 2023, nuestro equipo de Plataforma de Desarrolladores —el equipo que interactúa directamente con nuestros desarrolladores externos de forma habitual a través de Twitter, Slack y otros canales— dedicó una semana a auditar nuestra API existente, registrando y agrupando los "pequeños problemas de la API" para identificar cómo debíamos rediseñar nuestros cimientos para desarrolladores.

Esta es la primera parte de una serie de blogs que ofrece una mirada entre bastidores a nuestro viaje de diseño, ingeniería, escalado y lanzamiento de una API renovada para todos los desarrolladores externos de Webflow (¡y ahora hay muchos más que en 2015!).

Realización de un ejercicio de detección de problemas

El primer paso que dimos fue sumergirnos en los pequeños problemas de la API. Asignamos una semana para identificar las brechas y limitaciones de nuestras API de aquel entonces (v1) y encontrar todas esas pequeñas molestias que suponían un dolor de cabeza para nuestros desarrolladores externos. Además, definimos una guía de estilo de API pública que establecía nuestros principios de diseño y mejores prácticas para prepararnos para el éxito durante el desarrollo de la siguiente versión de nuestras API (v2).

Llevamos a cabo un ejercicio en el que preparamos una lista de problemas (basada en los comentarios tanto internos como de desarrolladores externos) asociados con nuestro conjunto de API. Clasificamos las brechas y limitaciones en los siguientes temas: errores de respuesta de la API, vertical de la API de usuarios/membresía de Webflow, ergonomía de la API, nomenclatura y webhooks.

La secuencia de actividades orientadas a procesos que ejecutamos se detalla a continuación:

Paso 1

Filtramos las principales peticiones de los desarrolladores, junto con los problemas y tareas de nuestros tableros de JIRA, para identificar los temas populares dentro de las categorías mencionadas y preparamos un espacio de muestra de elementos temáticos.

Paso 2

Empezamos a debatir en nuestro grupo de trabajo para priorizar los temas en los siguientes pasos prácticos:

• Requiere más exploración (sí/no)
• Actualizar la documentación pública para desarrolladores (sí/no)
• Actualizar la guía de estilo (sí/no)
• Se busca opinión adicional de los desarrolladores (sí/no/comentarios)
• Más detalles/próximos pasos

Un ejemplo de cómo abordamos la priorización:

Paso 3

Preparamos una guía de estilo para la API pública que establece nuestros principios de diseño y mejores prácticas. La guía se dividió en los siguientes temas:

• Convenciones de nomenclatura para nuestros endpoints, alcances y campos de la API
• Entidades de respuesta de la API: tipos de datos (valores nulos, objetos, matrices, booleanos, etc.), códigos de estado HTTP y estandarización de errores
• Fundamentos de estructura: estructura de endpoints y convenciones de paginación
• Especificación de Open API

Paso 4

Comenzar a integrar la guía de estilo y los pasos prácticos priorizados del ejercicio "Papercuts" para impulsar nuestra iniciativa interdepartamental de renovación y lanzamiento de nuestra suite de API.

Lecciones aprendidas

Crear una plataforma para desarrolladores requiere iteración y reflexión constantes. Al añadir nuevas funciones, es importante considerar cómo encaja cada nuevo endpoint en los patrones ya establecidos. Aun así, a medida que una API madura, es inevitable que acumule ciertas peculiaridades, inconsistencias y diseños que han ido más allá de su propósito original.

Lanzar una nueva versión de la API ofrece una oportunidad única para reevaluar estas decisiones pasadas y rediseñar de forma integral cómo encajan los componentes de la API como un conjunto coherente. Es una gran responsabilidad que requiere una estrecha colaboración con las partes interesadas, así como una comprensión clara de los escenarios de los desarrolladores y el rumbo de la organización. Realizar una auditoría exhaustiva de las API existentes es el primer paso crítico para marcar este camino.

No te pierdas la segunda parte de esta serie, donde profundizaremos en nuestros próximos esfuerzos sobre prácticas de versionado, ciclo de vida de lanzamiento, diseño de alcances de API y comunicación con el cliente.