フローチャートを使用したRESTインターフェースの文書化

RESTスタイルのWebインターフェースのフローチャート表現の作成に関する提案はありますか？共同開発者に完全なドキュメントを提供するために、製品リソースを変更および生成するためのインターフェースをモデリングするために、いじくり回してきました。

この特定のシステムは、ユーザー認証/リソース数によって異なる動作を開始するため、変更を加える前に、いくつかの明確化を探しています。

• 複雑さ：全体の構造を単純化してこれを読みやすくするにはどうすればよいですか？
• 表示記号：これはページを表すのに適していますか？
• 手動操作記号：これは、ボタンクリックなどのユーザーアクションを表すのに適していますか？

他の提案は大歓迎です。

再投稿をお詫び申し上げます。メインのstackexchangeサイトは、この質問はプログラマーにより適切に提示されることを示唆しています。

メッセージシーケンスチャート/シーケンス図は、RESTful APIの相互作用を文書化するのに適していると思います。あなたが持っているのは状態図ですが、RESTful APIは本質的にステートレスです。

ステートマシンは、RESTfulシステムの相互作用を文書化する正しい方法だと思います。ただし、ダイアグラムでハイパーメディア要素を表現するための正しい方法については、引き続き取り組んでいます。ここに私が行ったいくつかの実験図があります。

現時点でこれに取り組んでいるので、この件に関する私の2つのペニー：

• リソースとその関係に焦点を当てる
  
  • アクションではなく、したがってHTTPメソッド
  • リンクをたどると、GETまたはPOSTを実行したかどうかに関係なく、次の可能な状態は主に現在のリソースによって決定され、リクエストのHTTPメソッドによって決定されません。

それを念頭に置いて：

• いくつかの明らかなリンク（つまり、自己、ルートへ）を削除
• "this [car] has a [owner]"と表示されている場合は、関係のラベルを削除します。この場合、ソースリソースはcarで、ターゲットリソースはownerです。何も追加されません
• インタラクティブなグラフは、複雑な状態図（例）に非常に役立ちます。