Me preguntaba si alguien podría dar algún consejo sobre los pros y los contras entre usar Mashery versus Apigee para documentar una API. He evaluado un poco y tengo alrededor de 2 semanas para presentar una propuesta sobre cuál usar. He usado Mashery pero no Apigee lo suficiente como para saber cuáles son las diferencias.
Cualquier recurso que pueda señalarme o un consejo anecdótico que pueda darme sería muy apreciado.
También publiqué esta pregunta en el grupo de escritores de API, pero la estoy publicando de forma cruzada porque este grupo tiene una audiencia más amplia.
Gracias de antemano.
Es difícil hacer una comparación cara a cara porque no es muy frecuente encontrar a alguien que tenga experiencia en el uso de Mashery y Apigee. Entonces, desde el lado de Mashery, puedo comentar sobre lo que está disponible porque estoy muy familiarizado con la solución.
Para documentar una API, Mashery tiene dos características de producto que vienen de serie con todos los clientes: (1) CMS (sistema de administración de contenido) de documentación de formato largo con control de acceso basado en roles y (2) documentación interactiva (I/O Docs) con integración de autorización completa .
El CMS para documentos de formato largo es simple. Proporciona una manera fácil de crear documentos jerárquicos con un editor HTML WYSIWYG simple o HTML directo. También tiene control de estilo completo con plantillas CSS o incluso CSS inyectable en línea, así como la capacidad de cargar JS remoto o también realizar JS inyectado en línea.
Ejemplos de formato largo:
Tribune Media Services: http://developer.tmsapi.com/docs/read/data_v1/lineups/Lineups_by_zipcode
Expedia Affiliate Network: http://developer.ean.com/docs/read/hotel_list
Para los documentos interactivos, Mashery ofrece I/O Docs. I/O Docs está configurado con un esquema JSON y está integrado en el portal para desarrolladores, de modo que cuando un desarrollador inicia sesión, los esquemas de autorización y las claves API se completan automáticamente. I/O Docs es flexible y, para bien o para mal, está separado de cualquier otra definición de API, lo que permite que un escritor técnico configure I/O Docs para que se comporte no solo como un documento de referencia y una herramienta de prueba, sino también como una herramienta de aprendizaje ( es decir, configuración paso a paso con descripciones detalladas sobre recursos, métodos y parámetros).
Ejemplos de documentos de E/S:
FoodEssentials: http://developer.foodessentials.com/io-docs (step-by-step style)
Tribune Media Services: http://developer.tmsapi.com/io-docs
EPSN: http://developer.espn.com/io-docs
Con Mashery, tanto el tráfico como la gestión del portal se realizan en un solo lugar. Todo está muy unido. Por supuesto, esa es una de las mayores diferencias: la administración. Nuevamente, para bien o para mal, Apigee usa Drupal como CMS y funciona como una unidad separada que necesita ser administrada. El contraste sería que la pila del portal para desarrolladores de Mashery es SaaS de múltiples inquilinos y está completamente administrada.
Me vino a la mente una persona/empresa, Peter de SDK Bridge. Creo que su empresa ha escrito/implementado documentación para uno o más clientes de Mashery, así como para plataformas que no pertenecen a la familia Mashery. Es muy posible que ya esté aquí, pero si no, tal vez verifique si puede proporcionar una comparación: http://sdkbridge.com/documentation.php : no está asociado ni empleado con Mashery.
Descargo de responsabilidad: soy un evangelista de plataformas con Mashery (un evangelista de las API de nuestros clientes), por lo que conozco bastante bien a varios escritores técnicos y arquitectos de API. :)
¡Buena suerte!
Mónica Celio