DEV Community

Cover image for Plataforma API para Flujo de Trabajo API Design-First
Roobia
Roobia

Posted on • Originally published at apidog.com

Plataforma API para Flujo de Trabajo API Design-First

En resumen

El enfoque de diseño-primero consiste en escribir la especificación de tu API antes del código de implementación. Esa especificación se convierte en la fuente de verdad para mocks, documentación, pruebas y stubs de cliente. Si eliges una plataforma que conecte todo el flujo, reduces la fricción de mantener código, contrato y documentación sincronizados. En este artículo verás cómo aplicar diseño-primero en la práctica y cómo encaja Apidog como plataforma completa para este flujo.

Prueba Apidog hoy

Apidog

Prueba Apidog gratis

Introducción

La mayoría de los desarrolladores empiezan creando APIs con un enfoque de código-primero:

  1. Escribes una ruta.
  2. Añades anotaciones o decoradores.
  3. Ejecutas un generador.
  4. Obtienes documentación.

Funciona bien al principio. El problema aparece cuando la implementación cambia y la documentación no.

Ejemplo típico:

[
  "foo",
  "bar"
]
Enter fullscreen mode Exit fullscreen mode

La documentación dice que la API devuelve un array de strings, pero la implementación real termina devolviendo esto:

[
  {
    "value": "foo"
  },
  {
    "value": "bar"
  }
]
Enter fullscreen mode Exit fullscreen mode

Ese desajuste rompe integraciones, genera bugs en frontend y hace que los consumidores de la API pierdan confianza en la documentación.

El diseño-primero invierte el flujo:

Especificación OpenAPI
        ↓
Mocks
        ↓
Documentación
        ↓
Pruebas
        ↓
Implementación
Enter fullscreen mode Exit fullscreen mode

La especificación es la fuente de verdad. El código, los mocks y la documentación se derivan de ella o se validan contra ella.

Esto no es una diferencia teórica. En equipos frontend/backend, el diseño-primero permite trabajar en paralelo desde el primer día: frontend consume mocks, backend implementa contra el contrato y las pruebas validan que ambos coincidan.

La condición clave es que la herramienta haga que escribir la especificación sea rápido. Si definir un endpoint tarda más que implementarlo, el equipo terminará saltándose el diseño. Por eso una buena plataforma de diseño-primero debe hacer que la especificación sea fácil de crear, revisar y usar.

Qué significa diseño-primero en la práctica

Diseño-primero no es una tecnología específica. Es un flujo de trabajo.

1. Antes de escribir código

Primero defines el contrato de la API, normalmente como una especificación OpenAPI.

Debe incluir:

  • Rutas y métodos HTTP.
  • Parámetros de path, query y headers.
  • Esquemas de request body para POST, PUT y PATCH.
  • Esquemas de respuesta para códigos como 200, 400, 401, 422 y 500.
  • Reglas de autenticación.
  • Descripciones de campos.
  • Ejemplos de request y response.

Ejemplo simplificado de OpenAPI:

paths:
  /users/{id}:
    get:
      summary: Obtener usuario por ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: "Usuario encontrado"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserProfile"
        "404":
          description: "Usuario no encontrado"

components:
  schemas:
    UserProfile:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: integer
          example: 123
        email:
          type: string
          format: email
          example: user@example.com
Enter fullscreen mode Exit fullscreen mode

Esta fase es donde se toman decisiones importantes:

  • Nombres de campos.
  • Estructura de recursos.
  • Formato de errores.
  • Reglas de paginación.
  • Códigos de estado.
  • Compatibilidad hacia atrás.

2. Durante el desarrollo

La especificación se publica en un servidor mock.

El frontend puede consumir una URL simulada como si fuera la API real:

const response = await fetch("https://mock.example.com/users/123");
const user = await response.json();

console.log(user.email);
Enter fullscreen mode Exit fullscreen mode

Mientras tanto, backend implementa contra el contrato:

app.get("/users/:id", async (req, res) => {
  const user = await userRepository.findById(req.params.id);

  if (!user) {
    return res.status(404).json({
      code: "USER_NOT_FOUND",
      message: "User not found"
    });
  }

  return res.json({
    id: user.id,
    email: user.email
  });
});
Enter fullscreen mode Exit fullscreen mode

Frontend y backend ya no se bloquean mutuamente.

3. Después de implementar

Las pruebas validan que la respuesta real coincida con la especificación.

Por ejemplo, una prueba de contrato debería fallar si la API devuelve:

{
  "id": 123,
  "emailAddress": "user@example.com"
}
Enter fullscreen mode Exit fullscreen mode

cuando la especificación exige:

{
  "id": 123,
  "email": "user@example.com"
}
Enter fullscreen mode Exit fullscreen mode

El objetivo no es solo comprobar que la API responde, sino que responde con el contrato correcto.

4. Cuando cambian los requisitos

El cambio empieza en la especificación:

  1. Se actualiza el contrato.
  2. El equipo revisa el cambio.
  3. Los mocks se actualizan.
  4. La documentación refleja la nueva versión.
  5. Backend ajusta la implementación.
  6. Las pruebas detectan cualquier desviación.

Así evitas que la implementación se convierta en una fuente de verdad oculta.

Qué necesita una plataforma de diseño-primero

No todas las herramientas de API soportan bien este flujo. Una plataforma útil para diseño-primero debe cubrir estas piezas.

Editor visual de API

Editar YAML manualmente puede ser lento y propenso a errores de indentación.

Un buen editor visual debe permitir definir:

  • Método HTTP.
  • Ruta.
  • Parámetros.
  • Headers.
  • Request body.
  • Responses.
  • Schemas reutilizables.
  • Ejemplos.
  • Reglas de validación.

También debe generar OpenAPI válido y permitir reutilizar componentes.

Ejemplo de componente reutilizable:

components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
Enter fullscreen mode Exit fullscreen mode

Luego puedes usarlo en varios endpoints:

responses:
  "400":
    description: Solicitud inválida
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/ErrorResponse"
Enter fullscreen mode Exit fullscreen mode

Validación de OpenAPI

La especificación debe validarse mientras la editas.

La herramienta debería detectar errores como:

  • Campos requeridos faltantes.
  • $ref rotos.
  • Tipos inválidos.
  • Responses sin descripción.
  • Schemas mal estructurados.

Cuanto antes aparezca el error, más barato es corregirlo.

Generación automática de mocks

El flujo ideal es:

Definir endpoint → Guardar especificación → Obtener mock funcional
Enter fullscreen mode Exit fullscreen mode

Sin configuración manual adicional.

El mock debe respetar:

  • Tipos de datos.
  • Formatos (email, date-time, etc.).
  • Enumeraciones.
  • Rangos minimum / maximum.
  • Objetos anidados.
  • Arrays.
  • Referencias $ref.

Vista previa de documentación

La especificación debe poder renderizarse como documentación legible.

Esto permite revisar el contrato con:

  • Frontend.
  • Backend.
  • QA.
  • Product managers.
  • Stakeholders no técnicos.

Una buena vista previa debe mostrar:

  • Descripciones.
  • Parámetros.
  • Ejemplos.
  • Schemas.
  • Códigos de estado.
  • Reglas de autenticación.

Flujo de revisión en equipo

Los cambios en la especificación deben tratarse como cambios en código.

Un flujo práctico sería:

  1. Alguien propone un cambio.
  2. El equipo comenta.
  3. Se ajusta la especificación.
  4. Se aprueba.
  5. Se implementa.

La plataforma debe soportar comentarios, historial y trazabilidad.

Exportación a OpenAPI estándar

La especificación tiene que ser portable.

Debes poder exportarla como OpenAPI 3.x y usarla con otras herramientas:

  • Generadores de código.
  • Gateways API.
  • Frameworks de prueba.
  • Validadores de contrato.
  • Herramientas de documentación.

Apidog como plataforma de diseño-primero

Apidog está organizado alrededor de la especificación como artefacto principal. La pestaña de diseño, el servidor mock, el ejecutor de pruebas y la documentación se conectan a la misma definición de API.

Editor visual de OpenAPI

La interfaz de diseño de Apidog usa edición basada en formularios.

Para cada endpoint puedes definir:

  • Ruta.
  • Método.
  • Parámetros.
  • Request body.
  • Responses.
  • Schemas.
  • Descripciones.
  • Reglas de validación.
  • Datos de mock.

No necesitas escribir YAML si no quieres. También puedes abrir una vista raw para editar YAML o JSON directamente. Los cambios entre la vista visual y la vista raw se sincronizan.

Los componentes de esquema son reutilizables. Puedes definir un esquema UserProfile una vez y referenciarlo desde múltiples endpoints con $ref.

Ejemplo:

components:
  schemas:
    UserProfile:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
          format: email
        displayName:
          type: string
Enter fullscreen mode Exit fullscreen mode

Luego lo reutilizas:

schema:
  $ref: "#/components/schemas/UserProfile"
Enter fullscreen mode Exit fullscreen mode

Si cambias UserProfile, todos los endpoints que lo referencian reflejan ese cambio.

Vista previa de documentación en tiempo real

Mientras diseñas un endpoint, la documentación se actualiza en tiempo real.

Esto te permite comprobar si el contrato es entendible antes de implementar.

Revisa especialmente:

  • Si los nombres de campos son claros.
  • Si las descripciones explican el comportamiento.
  • Si los ejemplos son realistas.
  • Si los errores están documentados.
  • Si los códigos de estado son correctos.

Puedes compartir un enlace de documentación con producto o frontend durante la fase de diseño. No necesitan instalar nada para revisarlo.

Smart Mock: de especificación a mock funcional

Cuando guardas un endpoint nuevo en Apidog, el servidor mock queda disponible de inmediato. La URL del mock aparece en la interfaz.

El mock genera respuestas basadas en los schemas:

  • Los strings con format: email devuelven emails válidos.
  • Los enteros con minimum y maximum devuelven valores dentro del rango.
  • Los enums devuelven valores permitidos.
  • Los objetos y arrays anidados siguen la estructura definida.
  • Los componentes $ref se resuelven correctamente.

Ejemplo de schema:

UserProfile:
  type: object
  properties:
    id:
      type: integer
      minimum: 1
      maximum: 9999
    email:
      type: string
      format: email
    role:
      type: string
      enum:
        - admin
        - member
        - viewer
Enter fullscreen mode Exit fullscreen mode

El mock puede devolver algo como:

{
  "id": 42,
  "email": "user@example.com",
  "role": "member"
}
Enter fullscreen mode Exit fullscreen mode

También puedes configurar reglas personalizadas. Por ejemplo:

  • Devolver 404 cuando el parámetro id sea 0.
  • Devolver una respuesta específica para ?status=inactive.
  • Simular errores de validación para pruebas de frontend.

Revisión en equipo y seguimiento de cambios

En Apidog, los cambios en la especificación son visibles para los miembros del workspace.

El equipo puede:

  • Comentar endpoints.
  • Comentar campos específicos.
  • Revisar cambios.
  • Ver quién modificó qué y cuándo.

Para diseño-primero, esto evita procesos paralelos. La revisión del contrato ocurre en la misma herramienta donde se diseña, documenta, prueba y simula la API.

Diseño-primero vs. código-primero: compensaciones reales

Diseño-primero no siempre es la mejor opción. Depende del tipo de proyecto y del equipo.

Ventajas del diseño-primero

  • Frontend y backend pueden trabajar en paralelo.
  • La documentación es precisa porque nace del contrato.
  • Los problemas de integración aparecen antes.
  • El contrato de API es explícito y verificable.
  • Los cambios pasan por revisión.
  • Los mocks están disponibles desde el inicio.

Desventajas del diseño-primero

  • Requiere tiempo inicial para definir la especificación.
  • La herramienta de especificación tiene curva de aprendizaje.
  • Exige disciplina para mantener implementación y contrato sincronizados.
  • Puede llevar a especificar demasiado pronto si el dominio aún no está claro.

Ventajas del código-primero

  • Más rápido para prototipos pequeños.
  • Menos proceso para desarrolladores individuales.
  • No necesitas aprender una herramienta adicional.
  • Útil cuando la API cambia constantemente durante exploración.

Desventajas del código-primero

  • La documentación es secundaria y puede quedar obsoleta.
  • Frontend suele esperar a backend para integrar.
  • El contrato es implícito.
  • Los breaking changes son más difíciles de detectar.
  • Refactorizar la API requiere actualizar documentación manualmente.

Para equipos con más de un ingeniero trabajando en una API, diseño-primero suele dar mejores resultados. La inversión inicial se compensa cuando hay coordinación real entre frontend, backend, QA y producto.

Herramientas que soportan flujos de diseño-primero

Apidog

Apidog ofrece una plataforma completa para diseño-primero: editor visual, mocks instantáneos, documentación, pruebas y revisión en equipo en una sola herramienta. El nivel gratuito cubre el conjunto completo de funciones. Su generación de mocks es uno de sus diferenciadores principales.

Stoplight Studio

Stoplight Studio es un editor OpenAPI sólido con linting Spectral para aplicar reglas de estilo. No incluye servidor mock ni ejecutor de pruebas incorporados. Es útil para organizaciones que necesitan gobernanza de APIs, aunque puede resultar caro para equipos pequeños.

SwaggerHub

SwaggerHub es una plataforma madura para edición y colaboración sobre OpenAPI. Se usa mucho en empresas. Su capacidad de mock es limitada y no incluye pruebas. Encaja bien en organizaciones centradas en especificaciones dentro del ecosistema Swagger.

Postman con API Builder

Postman incluye una pestaña para diseño de APIs que genera especificaciones OpenAPI. Sin embargo, los flujos de diseño y colecciones pueden sentirse desconectados. El servidor mock requiere configuración manual a partir de colecciones, en lugar de generarse automáticamente desde la especificación. Funciona para equipos código-primero que quieren añadir documentación.

Insomnia con modo documento

Insomnia soporta edición de especificaciones OpenAPI y proporciona mock básico. Es menos completo que herramientas dedicadas a diseño-primero, pero puede servir para desarrolladores individuales que buscan una opción ligera.

Cómo configurar un flujo diseño-primero en Apidog

Paso 1: Empieza con la especificación, no con una colección

Crea un proyecto nuevo y abre la pestaña de diseño.

Antes de enviar una sola request, define como mínimo:

  • Ruta.
  • Método.
  • Parámetros principales.
  • Response esperado.
  • Schema de error.

Ejemplo de checklist para un endpoint:

[ ] Método HTTP definido
[ ] Ruta definida
[ ] Parámetros documentados
[ ] Response 200 definido
[ ] Response de error definido
[ ] Schema reutilizable si aplica
[ ] Ejemplo de respuesta incluido
Enter fullscreen mode Exit fullscreen mode

Paso 2: Define componentes compartidos primero

Antes de añadir muchos endpoints, define los schemas reutilizables.

Por ejemplo:

  • ErrorResponse
  • PaginationMeta
  • UserProfile
  • Address
  • CreatedResourceResponse

Ejemplo:

components:
  schemas:
    PaginationMeta:
      type: object
      properties:
        page:
          type: integer
        pageSize:
          type: integer
        total:
          type: integer
Enter fullscreen mode Exit fullscreen mode

Esto evita que cada endpoint invente su propio formato de paginación.

Paso 3: Obtén la URL del mock temprano

Cuando guardes el endpoint, copia la URL del mock y compártela con frontend.

Frontend puede empezar a integrar con algo como:

const API_BASE_URL = "https://mock.example.com";

export async function getUser(id) {
  const response = await fetch(`${API_BASE_URL}/users/${id}`);

  if (!response.ok) {
    throw new Error("Failed to fetch user");
  }

  return response.json();
}
Enter fullscreen mode Exit fullscreen mode

Cuando backend esté listo, solo se cambia el API_BASE_URL.

Paso 4: Revisa la documentación antes de implementar

Abre la vista previa de documentación y valida:

  • ¿La descripción del endpoint explica qué hace?
  • ¿Los parámetros tienen significado claro?
  • ¿Los ejemplos ayudan a consumir la API?
  • ¿Los errores esperados están definidos?
  • ¿El schema refleja lo que frontend necesita?

Si algo no se entiende en la documentación, tampoco será claro para quien consuma la API.

Paso 5: Bloquea la especificación para el sprint

Cuando el diseño esté revisado, trata la especificación como bloqueada para ese sprint.

Si backend descubre que necesita cambiar el contrato, el flujo debería ser:

Proponer cambio → Revisar con frontend/producto → Actualizar especificación → Implementar
Enter fullscreen mode Exit fullscreen mode

No cambies silenciosamente la respuesta real.

Paso 6: Ejecuta validación de schema en CI

Configura pruebas para comprobar que la implementación real coincide con la especificación.

El objetivo es detectar automáticamente cambios como:

  • Campos faltantes.
  • Tipos incorrectos.
  • Códigos de estado no documentados.
  • Estructuras de error inconsistentes.
  • Responses incompatibles con el schema.

Esta es la barrera que mantiene sincronizados contrato e implementación.

Preguntas frecuentes

¿El diseño-primero es solo para APIs REST?

No. El principio aplica a cualquier protocolo donde puedas definir un contrato:

  • REST con OpenAPI.
  • GraphQL con schema-first.
  • gRPC con protobuf.
  • Sistemas event-driven con AsyncAPI.

Apidog soporta diseño REST y GraphQL. Para gRPC, los archivos proto cumplen el mismo rol de contrato primero.

¿Tenemos que definir todos los endpoints antes de empezar?

No. Puedes adoptar diseño-primero por funcionalidad.

Por ejemplo, si vas a construir una nueva pantalla de perfil de usuario, define primero los endpoints necesarios para esa pantalla, aunque otras partes del sistema sigan siendo código-primero.

La adopción incremental funciona bien.

¿Cómo encaja diseño-primero con sprints ágiles?

Al inicio del sprint, el equipo define el contrato de API para las funcionalidades planificadas.

Luego:

  • Frontend trabaja contra mocks.
  • Backend implementa contra la especificación.
  • QA revisa escenarios desde el contrato.
  • La documentación queda lista como parte del flujo.

La revisión de especificación pasa a formar parte de la planificación técnica del sprint.

¿Qué pasa si la implementación necesita diferir de la especificación original?

Puede pasar.

El proceso correcto es:

  1. Actualizar la especificación.
  2. Revisar el cambio con los interesados.
  3. Actualizar mocks y documentación.
  4. Modificar la implementación.
  5. Ejecutar pruebas de contrato.

Así la especificación sigue siendo la fuente de verdad.

¿Podemos generar stubs de servidor desde la exportación OpenAPI de Apidog?

Sí. Puedes exportar la especificación de Apidog como OpenAPI 3.x y usar generadores estándar para crear stubs de servidor.

Por ejemplo, con openapi-generator puedes generar código base para distintos lenguajes y frameworks.

Flujo típico:

Exportar OpenAPI → Ejecutar generador → Implementar handlers → Validar contra contrato
Enter fullscreen mode Exit fullscreen mode

¿Cómo manejamos el versionado de la especificación?

Apidog mantiene historial de cambios dentro del proyecto.

Para versiones mayores que conviven en paralelo, como v1 y v2, puedes usar proyectos o ramas separadas.

Ejemplo:

api-users-v1
api-users-v2
Enter fullscreen mode Exit fullscreen mode

O bien:

main
v2-design
Enter fullscreen mode Exit fullscreen mode

según el flujo de trabajo del equipo.

Conclusión

El diseño-primero exige una pequeña inversión inicial: definir el contrato antes de implementar. A cambio, reduce costos de integración, mejora la colaboración entre frontend y backend y mantiene la documentación alineada con la API real.

La herramienta importa. Si escribir la especificación es lento o incómodo, el equipo la evitará. Un editor visual, mocks instantáneos, documentación en tiempo real y pruebas de contrato hacen que diseño-primero sea práctico.

Apidog combina esas piezas en un flujo único, lo que ayuda a convertir la especificación en el centro del desarrollo de APIs, no en una tarea secundaria al final del sprint.

Top comments (0)