¿Cómo documentar los requisitos para una API sistemáticamente?

Actualmente estoy trabajando en un proyecto, donde tengo que analizar los requisitos de dos sistemas de TI dados, que usan la computación en la nube, para una API en la nube. En otras palabras, tengo que analizar qué requisitos tienen estos sistemas para una API en la nube, de modo que puedan cambiarla, al tiempo que puedan cumplir sus objetivos actuales.

Permíteme darte un ejemplo de algunos requisitos informales del Proyecto A:

1. Al iniciar máquinas virtuales en la nube a través de la API, debe ser posible especificar el tamaño de la memoria, el tipo de CPU, el sistema operativo y una clave SSH para el usuario root.
2. Debe ser posible monitorear el tráfico de red entrante y saliente por hora por máquina virtual.
3. La API debe admitir la asignación de IP públicas a una máquina virtual y la recuperación de las IP públicas.
4. ...

En una etapa posterior del proyecto analizaré algunos estándares de Cloud Computing que estandarizan las API de la nube para averiguar dónde están las posibles deficiencias en los estándares actuales. Un hallazgo podría ser, y probablemente será, que un determinado estándar no admite el monitoreo del uso de recursos y, por lo tanto, actualmente no es utilizable.

Actualmente estoy tratando de encontrar una manera de anotar sistemáticamente y clasificar mis requisitos. Siento que la forma en que las tengo escritas actualmente (como los tres puntos anteriores) es demasiado informal.

He leído en un par de libros sobre ingeniería de requisitos y arquitectura de software, pero todos se centran demasiado en los detalles y la implementación. Realmente solo me interesan las funcionalidades proporcionadas a través de la API / interfaz y no creo que los diagramas UML, etc.son la opción correcta para mí. Creo que actualmente los requisitos que recopilé pueden describirse como historias de usuarios, pero ¿ya son suficientes para un análisis de requisitos sofisticado? Probablemente debería ir "un nivel más profundo" ...

Lea Documenting Software Architectures, segunda edición: Views and Beyond , Capítulo 7: Documentación de interfaces de software.

O al menos revise algunas documentaciones API conocidas, como las de Amazon ( Maps , GData , desactualizadas pero complejas) de Amazon ( S3 ) o inspeccione la documentación para aplicaciones y servicios de Microsoft, reunidos en MSDN (para servicios en vivo , pero incluso para Windows )

Por lo general, una documentación API tiene 3 partes:

• una visión general de para qué sirve, qué podría hacer alguien de ella, tal vez una descripción arquitectónica
• Una guía del desarrollador, que explica algunas tareas comunes con la API, generalmente con ejemplos de código y aplicaciones de muestra descargables.
• Una referencia API de cómo debería funcionar

En teoría , si creemos en el Mes del Hombre Mítico de Brook, usted diseña la documentación y se asegura de que haya una implementación adecuada.

Ahora de vuelta a la práctica

Los requisitos de diseño para una API son como cualquier diseño de software.

1. Alistar a los diferentes actores que van a utilizar la API (utilizando un diagrama de contexto, por ejemplo)
2. Detalla las necesidades típicas del sistema de cada actor con casos de uso
3. Para cada caso de uso, desarrolla un conjunto de escenarios sobre cómo se usaría el sistema imaginado (el libro Escritura de casos de uso efectivo podría ayudarlo en eso)
4. Puede crear diagramas de robustez , diagramas de secuencia o diagramas de actividad , pero diseña el comportamiento en función de los escenarios para distinguir qué mensajes deben transmitirse
5. A partir de los mensajes, deduce la arquitectura de datos subyacente , al observar qué parámetros son necesarios para que cada mensaje se comunique con éxito.

Muchas personas comenzarían con la estructura de datos subyacente, pero creo que es una tontería: las computadoras (y los objetos, de hecho) tratan sobre interacciones. Debe comprender lo que debe comunicarse desde cualquier lado para ejecutar una interacción exitosa. Los datos son solo el parámetro de esas interacciones.

Usualmente hago diagramas de actividades o diagramas de flujo simples que muestran los argumentos pasados ​​como objetos o clases. Es decir, hay un flujo de control en curso, pero vemos qué información pasó una de las partes a la otra.

Una vez que haya terminado todo esto, vuelve a tomar sus escenarios y comienza a elaborar pruebas de aceptación . Esto se debe a que los clientes informáticos deben utilizar las API, por lo tanto, su primer código debe ser un cliente informático que realice la recuperación automática como prueba.

Las pruebas de aceptación se escriben en forma de "entrada proporcionada" - "salida esperada", o como código. Puede encontrar muchos libros sobre BDD y TDD que le explicarán cómo escribir buenas pruebas.

Además, por aquí, comienza a sacar libros sobre interfaces REST y similares en caso de que esté creando una API web, ya que sus pruebas deben ser ejecutables desde el primer día.

A partir de los escenarios, también crea código de muestra y una guía para desarrolladores.

A partir de los diagramas de secuencia y los diagramas de arquitectura de datos, usted desarrolla la referencia API.

Agregue una pizca de HTML, asegúrese de que todas las pruebas pasen y que su aplicación sea lo suficientemente rápida, segura y robusta, ¡y salgamos con eso!

(Lo sé, esto fue en cascada: ágil es lo mismo, excepto que siempre haces solo una pequeña parte de esto, por ejemplo, algunos escenarios por sprint)

Realmente no necesita ser más "formal" de lo que tiene. Lo estás escribiendo para que lo lean los humanos y probablemente sobre todo tú mismo, así que tenlo en cuenta. Mi única sugerencia es ponerlo en una jerarquía y numerarlo en formato de esquema. De esa manera, en las revisiones, listas de verificación y demás, puede referirse a un número como 3.0.1 como una abreviatura y desambiguar fácilmente de lo que está hablando.