Si entregable es de hecho un conjunto de servicios web, entonces consideraría esto como un ejercicio de diseño de API. Probablemente no desee hacer una especificación adecuada, ya que esto es algo que debería ser el rol de un arquitecto de software. Lo que debe hacer es describir los casos de uso de cómo se utilizará la API y dejar los detalles técnicos. Incluso en este caso, es posible que desee agregar algunos requisitos genéricos en las propiedades de la API (algunos pueden considerarse como elementos para los que el equipo de desarrollo debería tener respuestas):
- Requisitos de seguridad : deberá decidir quién y cómo puede acceder a su servicio web, cómo se proporciona y verifica el acceso, cuáles son los derechos potenciales, si desea proporcionar una capacidad de auditoría, etc.
- ACIDIDAD de sus transacciones: para cada caso de uso, será importante comprender si la operación es: atómica, consistente, aislada y duradera.
- Requisitos de rendimiento y calidad de servicio : los casos de uso deben incluir requisitos de rendimiento. ¿Se supone que esta función procesa 1 línea o 100 millones, qué tan rápido debe ser el procesamiento?
- Manejo de errores / excepciones : asegúrese de que los errores / excepciones se manejen de manera adecuada y coherente
- Registro : en algún momento inevitablemente sucederá algo malo, los registros deben estar allí
- SECO : no se repita: una cosa / entidad / función debe definirse solo una vez
- Actualizaciones : en algún momento su API se actualizará, asegúrese de que tanto la API como su cliente estén listos para ello, piense en la coexistencia y / o la compatibilidad con versiones anteriores. A veces uno debe prepararse para una actualización antes de que suceda.
- Licencias : ¿se utilizará la API dependiendo de algún tipo de licencia? ¿De qué manera se verifican los parámetros de licencia? etc.
- Documentación : cualquier API es algo que se utilizará más adelante, por lo que debe documentarse adecuadamente y la documentación debe ser uno de los entregables.
- Nombres y coherencia : API es algo que será utilizado por otros, por lo que es importante que sea fácil de entender y seguir. Asegúrese de especificar convenciones de nomenclatura como uno de los requisitos
Y el más importante: cualquier API (servicio web en nuestro caso) es un producto donde los clientes son desarrolladores (ya sea dentro o fuera de su organización). Trátelos como tal . (Realice revisiones, recopile comentarios, cree varios (no menos de 3) clientes de su API para probarlos y recopile comentarios nuevamente e, incluso, implemente algunos de ellos).
Par de enlaces:
- ¿Debo aprender VueJs o AngularJS?
- Estoy convencido de que mi desarrollador está aumentando enormemente la cantidad de horas que le llevará completar un trabajo. ¿Cómo controlo esto? Por favor lea mi comentario.
- ¿Qué patrón de diseño usa la tubería del sombreador?
- ¿Por qué la profesión de ingeniería de software carece de un organismo de autogobierno / defensa? Por ejemplo, los contadores tienen el AICPA, los abogados tienen bares.
- ¿Qué idiomas aprenden todos los ingenieros informáticos?
- Aquí se puede encontrar una gran discusión sobre el diseño adecuado de API (algo técnico) por Joshua Bloch de Google: http://lcsd05.cs.tamu.edu/slides…
- Enfoque de la FAA para las especificaciones de servicios web (mucho más formalizado): http://www.faa.gov/about/office_…