Uno de los aspectos más importantes en el ciclo de vida de una API es, por supuesto, la fase de diseño; pero en orden de magnitud, justo después de esta, Orlando Kalossakas de Mashape coloca la fase de documentación.
Se puede diseñar con herramientas que, como Dreamweaver hacía para el desarrollo web, ayudan en la parte de diseño de forma brutal. Sin embargo, al contrario que con Dreamweaver, que era la herramienta estándar de facto para los desarrolladores web, en el espacio de diseño de una API hay muchas opciones entre las que elegir, tanto para diseñar como para documentar tu API. Recuerda que el diseño de una API resulta de repetir, repetir, repetir y repetir lo que funciona mejor para tu base de usuarios.
- Swagger por Swagger.io (basada en el lenguaje de definición de Swagger)
- Mashape’s API Editor por Mashape.com (basada en un editor visual)
- API Designer Studio por Mulesoft.com (basada en RAML)
- Readme by Readme.io (basada en RAML)
- Apiary’s API Explorer por apiary.io (basada en API Blueprint)
Y existen más, poco conocidas, que están surgiendo con toques innovadores en el diseño de la API y en el espacio de documentación.
Orlando ha explicado en APIdays Mediterranea que cada una de estas herramientas tiene ventajas y desventajas, pero que al final hay una lección clave que ningún diseñador de APIs o arquitecto puede olvidar: toda API debe ser construida de forma que los desarrolladores puedan entenderla y usarla de forma rápida. Cuanto más rápido puedan consumir tu API los desarrolladores, antes podrás empezar a analizar casos de uso.
Recoger el feedback sobre el uso y las situaciones que se dan te ayudará a repetir y crear una mejor API: piensa en las respuestas, los conectores y el procesamiento de datos que puedes conseguir y mejorar una vez que sepas qué esperan los desarrolladores de tu API.
El diseño de una API debe estar muy enfocado en la experiencia del desarrollador, en proporcionarle información exhaustiva para que tenga menos posibilidades de equivocarse. Con «desarrollador» Orlando no solo se refiere al desarrollador de la API externa, sino también al que algún día le tocará seguir desarrollándola y manteniendo la API que tú creaste.
Porque todos sabemos que las APIs han llegado para controlar el mundo, pero no olvides que hay más APIs privadas que públicas, así que los procesos de desarrollo de las APIs internas son igual de importantes. De ahí el por qué de que la experiencia del desarrollador, para los fanáticos de las APIs, es tan importante como la experiencia de usuario para los entusiastas del producto.
Se pueden encontrar más detalles sobre las herramientas arriba mencionadas en este enlace.