MSD-01-PHIL · Filosofía del ecosistema

MAG define el contrato. MSD entrega la experiencia.

Toda la operación. Una sola plataforma.

Objetivo del capítulo

Establecer la filosofía del ecosistema para desarrolladores de Roustix: cómo el transforma la documentación de la API en una experiencia práctica para integradores, partners y equipos de ingeniería.

1 · De contrato a experiencia

entregó MAG v1.0 — un estándar de API de nivel empresarial:

contrato REST /api/v1
JWT multi-tenant
errores estructurados
webhooks
ejemplos y buenas prácticas

responde la pregunta siguiente:

«Leí la documentación. ¿Cómo integro en producción esta semana?»

MSD (Roustix SDK & Developer Portal) cierra esa brecha.

Fase	Producto	Rol
	MAG	Especificación del contrato
	MSD	Herramientas, portal y clientes oficiales

2 · Filosofía

Un ecosistema de desarrolladores excelente debe ser:

Accesible — Quick Start en menos de 10 minutos
Consistente — mismo contrato en portal, SDK, CLI y colecciones
Generado — OpenAPI como fuente única de verdad
Multi-tenant aware — ejemplos y sandbox con contexto de empresa
Profesional — comparable a Stripe, GitHub, Microsoft Graph o Notion

La documentación no termina en la especificación. Debe incluir herramientas que funcionen.

3 · Componentes del ecosistema MSD

Roustix Developer Experience
│
├── Developer Portal      developer.roustix.app
├── OpenAPI 3.1           openapi.v1.yaml
├── SDK oficiales         Python · JavaScript · PHP
├── CLI                   roustix-cli
├── Sandbox               tenant demo · datos ficticios
├── API Explorer          Try it · desde OpenAPI
├── Quick Start           guías paso a paso
└── Colecciones           Postman · Insomnia

Cada componente consume el mismo contrato MAG.

4 · Relación con MAG

MAG	MSD
`/api/v1/auth/login`	`client.auth.login()`
MAG-04 recursos	`client.maintenance.assets`
MAG-06 errores	SDK lanza `RoustixError(code=...)`
MAG-09 ejemplos	Quick Start ejecutable
MAG-07 OpenAPI	`openapi.v1.yaml` generado

Regla: MSD nunca redefine el contrato. Solo lo implementa.

→ MAG v1.0

5 · Audiencias

Audiencia	Necesidad	Entrega MSD
Integrador interno	Automatizar procesos	SDK + Quick Start
Partner SaaS	Conectar ERP/CRM	Portal + colecciones
Desarrollador freelance	Prototipo rápido	Sandbox + Explorer
Equipo Roustix	Validar contrato	OpenAPI + CLI

Developer Docs (suite 09) sigue siendo para quien contribuye al repositorio — no confundir con MSD.

6 · Principios de diseño

#	Principio
1	OpenAPI primero — no escribir clientes a mano si pueden generarse
2	SDK idiomático por lenguaje — Python `snake_case`, JS `camelCase` en superficie
3	Ejemplos copiables — funcionan sin modificación significativa
4	Sandbox aislado — nunca datos de producción
5	Versionado alineado a MAG — MSD v1.0 sobre MAG v1.0
6	Publicación reproducible — CI publica paquetes desde tags

7 · Entregables

Entrega	Descripción	Capítulo
Portal	developer.roustix.app	MSD-02
OpenAPI 3.1	`openapi.v1.yaml`	MSD-03
SDK	Python · JS · PHP	MSD-04
CLI	`roustix-cli`	MSD-05
Sandbox	API Explorer	MSD-06
Quick Start	Guías	MSD-07
Colecciones	Postman · Insomnia	MSD-08
Publicación	Primer paquete SDK	MSD-09

8 · Entorno local

Recurso	URL local
MSD (este manual)	http://127.0.0.1:5000/msd/
MAG (contrato)	http://127.0.0.1:5000/mag/
API	http://127.0.0.1:5000/api/v1
Docs suite	http://127.0.0.1:5000/docs/

python run.py

MSD v1.0 se considerará completo cuando:

[ ] Existe portal accesible (local o developer.roustix.app)
[ ] OpenAPI 3.1 publicado y sincronizado con MAG-04
[ ] Al menos un SDK oficial publicado (Python recomendado)
[ ] Quick Start ejecutable de principio a fin
[ ] Colección Postman generada desde OpenAPI
[ ] Sandbox con tenant demo operativo

← Índice 02 · Portal →