Documentazione di un'interfaccia REST con un diagramma di flusso

8

Qualcuno ha suggerimenti sulla creazione di una rappresentazione del diagramma di flusso di un web in stile REST interfaccia? Nell'interesse di fornire una documentazione approfondita ai co-sviluppatori, ho cercato di modellare l'interfaccia per modificare e generare una risorsa di prodotto:

Questo particolare sistema inizia ad agire in modo diverso con i conteggi di autenticazione / risorsa dell'utente, quindi prima di apportare modifiche, sto cercando qualche chiarimento:

  • Complessità: come semplificheresti la struttura generale per rendere più facile la lettura?
  • Simbolo di visualizzazione: è appropriato per rappresentare una pagina?
  • Simbolo di operazione manuale: è appropriato per rappresentare un'azione dell'utente come un clic del pulsante?

Qualsiasi altro suggerimento sarebbe molto apprezzato.

Le mie scuse per il re-post. Il principale sito di stackexchange ha suggerito che questa domanda fosse presentata meglio sui programmatori.

    
posta James Kassemi 27.07.2011 - 17:49
fonte

3 risposte

12

Ritengo che il diagramma di sequenze di messaggi / diagramma di sequenze sia più adatto per documentare l'interazione dell'API RESTful. Quello che hai è un diagramma di stato, mentre l'API RESTful per definizione è senza stato.

    
risposta data 27.07.2011 - 18:02
fonte
1

Penso che una macchina a stati sia il modo giusto per documentare le interazioni di un sistema RESTful. Tuttavia, sto ancora lavorando al modo giusto per rappresentare i fattori ipermediali nel diagramma. Qui ci sono un paio di diagrammi sperimentali che ho fatto.

    
risposta data 02.08.2011 - 14:06
fonte
0

I miei due penny sul tema, visto che sto lavorando con questo al momento:

  • concentrarsi sulle risorse e le loro relazioni
    • e non sull'azione, e quindi il metodo HTTP
    • quando segui un link, non importa se hai fatto un GET o POST, i tuoi prossimi stati possibili sono dettati principalmente dalla risorsa corrente e molto meno dal metodo HTTP della richiesta

Con questo in mente:

  • rimuovi alcuni collegamenti ovvi (cioè a se stessi, a root)
  • rimuovi l'etichetta delle relazioni se indica semplicemente "questa [auto] ha un [proprietario]", dove la risorsa di origine è auto e la risorsa di destinazione è il proprietario. Non aggiunge nulla
  • un grafico interattivo può essere di grande aiuto con un diagramma di stato complesso ( example )
risposta data 16.12.2012 - 22:30
fonte

Leggi altre domande sui tag