Documentar una interfaz REST con un diagrama de flujo

¿Alguien tiene sugerencias para crear una representación de diagrama de flujo de una interfaz web de estilo REST? En el interés de proporcionar documentación exhaustiva a los co-desarrolladores, he estado jugando en el dia modelado de la interfaz para modificar y generar un recurso de producto:

Este sistema en particular comienza a actuar de manera diferente con la autenticación de usuarios / recuentos de recursos, por lo que antes de realizar modificaciones, estoy buscando alguna aclaración:

Complejidad: ¿cómo simplificaría la estructura general para que sea más fácil de leer?
Símbolo de visualización: ¿es apropiado para representar una página?
Símbolo de operación manual: ¿es apropiado para representar una acción del usuario como un clic de botón?

Cualquier otra sugerencia sería muy apreciada.

Mis disculpas por la nueva publicación. El sitio principal de stackexchange sugirió que esta pregunta se presentara mejor en los programadores.

documentation rest flowchart

— James Kassemi
fuente

Respuestas:

Creo que el diagrama de secuencia de mensajes / diagrama de secuencia es más adecuado para documentar la interacción API RESTful. Lo que tiene es un diagrama de estado, mientras que RESTful API por definición no tiene estado.

ingrese la descripción de la imagen aquí

— vartec
fuente

El servidor en una arquitectura RESTful no tiene estado, sin embargo, el sistema en sí no lo es. El estado se almacena en el cliente, y las posibles transiciones de estado se codifican dentro de la representación de un recurso para que el cliente pueda iniciar la transición a un nuevo estado haciendo una solicitud al servidor. Creo que un diagrama de estado es bastante efectivo para comunicar el estado general del sistema, incluso si no documenta con precisión las solicitudes y respuestas entre el cliente y los componentes del servidor.

— Adam Jaskiewicz

@ Adam: tienes razón sobre el sistema general. Pero la pregunta es explícita sobre la documentación de la interfaz REST, no todo el sistema.

— vartec

Gracias, vartec, el MSC documenta efectivamente la interfaz REST en este caso. Todavía tengo curiosidad por escuchar mejoras en la documentación de este modelo del estado del cliente.

— James Kassemi

Los sistemas RESTful que implementan la restricción de hipertexto hacen que el cliente actúe como una máquina de estados. He encontrado que usar diagramas de tipo de máquina de estado es una herramienta mucho más efectiva para documentar las interacciones RESTful cliente / servidor.

— Darrel Miller el

¿Es posible describir if-s y while-s en este diagrama?

— hellboy

Definitivamente creo que una máquina de estados es la forma correcta de documentar las interacciones de un sistema RESTful. Sin embargo, todavía estoy trabajando en la forma correcta de representar los factores hipermedia en el diagrama. Aquí hay un par de diagramas experimentales que he hecho.

Laberinto

ingrese la descripción de la imagen aquí

— Darrel Miller
fuente

Mis dos centavos sobre el tema, ya que estoy trabajando con esto en este momento:

centrarse en los recursos y sus relaciones
- y no en la acción, y por lo tanto el método HTTP
- cuando sigue un enlace, no importa si realizó una OBTENCIÓN o una POST, los siguientes estados posibles están dictados principalmente por el recurso actual, y mucho menos por el método HTTP de la solicitud.

Con eso en mente:

eliminar algunos enlaces obvios (es decir, a sí mismo, a la raíz)
elimine la etiqueta de las relaciones si solo dice "este [automóvil] tiene un [propietario]", donde el recurso de origen es el automóvil y el recurso de destino es el propietario. No agrega nada
Un gráfico interactivo puede ser de gran ayuda con un diagrama de estado complejo ( ejemplo )

— Andrei Neculau
fuente