RESTフローチャートとのインターフェースを文書化する
RESTスタイルのWebインターフェースのフローチャート表現の作成に関する提案はありますか？共同開発者に完全なドキュメントを提供するために、製品リソースを変更および生成するためのインターフェースをモデリングするために、いじくり回してきました。
この特定のシステムは、ユーザー認証/リソース数によって異なる動作を開始するため、変更を加える前に、いくつかの明確化を探しています。
- 複雑さ：全体の構造を単純化して、これを読みやすくするにはどうしますか？
- 表示記号：これはページを表すのに適していますか？
- 手動操作記号：これは、ボタンクリックなどのユーザーアクションを表すのに適していますか？
他の提案は大歓迎です。
再投稿をお詫び申し上げます。メインのstackexchangeサイトは、この質問はプログラマーにより適切に提示されることを示唆しています。
メッセージシーケンスチャート/シーケンス図は、RESTful APIの相互作用を文書化するのに適していると思います。あなたが持っているのは状態図ですが、RESTful APIは本質的にステートレスです。
ステートマシンは、RESTfulシステムの相互作用を文書化する正しい方法だと思います。ただし、ダイアグラムで ハイパーメディアファクター を表すための正しい方法については、まだ作業中です。ここに私が行ったいくつかの実験図があります。
現時点でこれに取り組んでいるので、この件に関する私の2つのペニー：
- リソースとその関係に焦点を当てる
- アクションではなく、したがってHTTPメソッド
- リンクをたどると、GETまたはPOSTを実行したかどうかに関係なく、次の可能な状態は主に現在のリソースによって決定され、リクエストのHTTPメソッドによって決定されません。
それを念頭に置いて：
- 明らかなリンクをいくつか削除します（つまり、自分へ、ルートへ）
- 「this [car] has a [owner]」とのみ表示されている場合は、関係のラベルを削除します。この場合、ソースリソースはcarで、ターゲットリソースはownerです。それは何も追加しません
- インタラクティブなグラフは、複雑な状態図（ 例 ）で非常に役立ちます。