APIの要件を体系的に文書化する方法は？
現在、私はプロジェクトに取り組んでいます。そこでは、クラウドコンピューティングを使用する、指定された2つのITシステムの要件を分析する必要があります。言い換えれば、私はこれらのシステムがクラウドAPIに対してどのような要件を持っているかを分析し、彼らが現在の目標を達成しながら、それを切り替えることができるようにする必要があります。
プロジェクトAの非公式な要件の例を挙げましょう。
- APIを介してクラウドで仮想マシンを起動する場合、ルートユーザーのメモリサイズ、CPUタイプ、オペレーティングシステム、SSHキーを指定できる必要があります。
- 仮想マシンごとに1時間あたりのインバウンドおよびアウトバウンドネットワークトラフィックを監視できる必要があります。
- APIは、仮想マシンへのパブリックIPの割り当てとパブリックIPの取得をサポートする必要があります。
- ...
プロジェクトの後の段階で、クラウドAPIを標準化するいくつかのクラウドコンピューティング標準を分析して、現在の標準の潜在的な欠点がどこにあるかを見つけます。特定の標準はリソースの使用状況の監視をサポートしていないため、現在は使用できないという結果がおそらくあります。
私は現在、体系的に自分の要件を書き留めて分類する方法を見つけようとしています。私が現在それらを書き留めている方法（上記の3つの点のように）はあまりにも非公式です。
私はいくつかの要件エンニーリングとソフトウェアアーキテクチャの本を読みましたが、それらはすべて詳細と実装に集中しすぎています。私は本当にAPI /インターフェースを介して提供される機能にのみ関心があり、UMLダイアグラムなどは私にとって正しい選択だとは思いません。現在収集した要件はユーザーストーリーとして説明できると思いますが、高度な要件分析にはこれで十分ですか？たぶん私は「一段階深く」行くべきだ...
Documenting Software Architectures、second edition：Views and Beyond 、Chapter 7：Documenting Software Interfacesを読んでください。
または、少なくともGoogle（ Maps 、 GData -時代遅れですが複雑）Amazon（ S ）などのよく知られたAPIドキュメントを確認するか、 [〜＃〜] msdn [〜＃〜] （ ライブサービス の場合、 Windows の場合も含む）にまとめられたMicrosoftアプリケーションおよびサービスのドキュメント=）
通常、APIドキュメントには3つの部分があります。
- 物事の目的、誰かがそれから何を作ることができるか、おそらく建築の概要
- 開発者ガイド。APIの一般的なタスクを説明します。通常、コードサンプルとダウンロード可能なサンプルアプリケーションが含まれます。
- どのように機能するかのAPIリファレンス
理論的には-BrooksのMythical Man Monthを信じている場合、ドキュメントを設計し、一致する実装があることを確認します。
今すぐ練習に戻ります
APIの設計要件は、他のソフトウェア設計と同様に行われます。
- APIを使用するさまざまな actors に参加します（たとえば コンテキスト図 を使用）
- システムの各アクターの典型的なニーズを 使用例 で詳しく説明します
- ユースケースごとに、想像上のシステムがどのように使用されるかについて一連のシナリオを作成します（本 Writing Effective Use Cases が役立つかもしれません）
- ロバスト図 、 シーケンス図 または アクティビティ図 のいずれかを作成しますが、動作に基づいて設計します scenarios は、どの messages が渡される必要があるかを明らかにする
- メッセージから、基礎となるデータアーキテクチャを推定するには、各メッセージが正常に通信されるために必要なパラメーターを調べます。
多くの人は基礎となるデータ構造から始めますが、それはばかげていると思います。コンピューター（およびオブジェクト）は相互作用に関するものです。正常な対話を実行するには、どちら側から何を通信する必要があるかを理解する必要があります。データはそれらの相互作用のパラメーターにすぎません。
私は通常、渡された引数をオブジェクトまたはクラスとして表示するアクティビティ図または単純なフローチャートを実行します。つまり、進行中の制御フローがありますが、一方の当事者が他方にどの情報を渡したかがわかります。
後これらをすべて完了したら、 scenarios を再度取得して、クラフトを開始します受け入れテスト。これは、APIがコンピュータークライアントで使用されるためです。したがって、最初のコードは、テストとして自動取得を実行するコンピュータークライアントである必要があります。
受け入れテストは、「提供された入力」-「期待される出力」の形式で、またはコードとして記述されます。優れたテストの書き方を説明するBDDとTDDに関する本はたくさんあります。
また、この辺りで RESTインターフェース に関する本を発表し始めます。テストを実行可能にする必要があるため、Web APIを構築している場合は同様です初日から。
シナリオから、サンプルコードと開発者ガイドも作成します。
シーケンス図とデータアーキテクチャ図から、APIリファレンスを作成します。
HTMLを少し追加して、すべてのテストに合格し、アプリケーションが高速、安全、かつ十分に堅牢であることを確認して、それを使い始めましょう！
（私は知っています、これは滝っぽいものでした：アジャイルは同じですが、常にこれのごく一部のみを実行します。たとえば、スプリントごとにいくつかのシナリオ）
あなたは本当にあなたが持っているものよりも「フォーマル」を取得する必要はありません。あなたはそれを人間が読むこと、そしておそらくほとんどが自分自身のためにそれを書いているので、それを覚えておいてください。私の提案の1つは、階層に配置し、アウトライン形式で番号を付けることです。このように、レビュー、チェックリストなどでは、3.0.1のような数字を省略形として参照し、話していることを簡単に明確にすることができます。