APIの要件を体系的に文書化する方法は？

私は現在プロジェクトに取り組んでいます。そこでは、クラウドコンピューティングを使用する2つの特定のITシステムの要件を分析して、クラウドAPIを取得する必要があります。言い換えれば、私はこれらのシステムがクラウドAPIに対してどのような要件を持っているかを分析し、彼らが現在の目標を達成しながら、それを切り替えることができるようにする必要があります。

プロジェクトAの非公式な要件の例を挙げましょう。

1. APIを介してクラウドで仮想マシンを起動する場合、rootユーザーのメモリサイズ、CPUタイプ、オペレーティングシステム、SSHキーを指定できる必要があります。
2. 仮想マシンごとに1時間あたりのインバウンドおよびアウトバウンドネットワークトラフィックを監視できる必要があります。
3. APIは、仮想マシンへのパブリックIPの割り当てとパブリックIPの取得をサポートする必要があります。
4. ...

プロジェクトの後の段階で、クラウドAPIを標準化するいくつかのクラウドコンピューティング標準を分析して、現在の標準の潜在的な欠点がどこにあるかを見つけます。特定の標準はリソースの使用状況の監視をサポートしていないため、現在は使用できないという結果がおそらくあります。

現在、体系的に自分の要件を書き留めて分類する方法を模索しています。私が現在それらを書き留めている方法（上記の3つの点のように）はあまりにも非公式です。

私はいくつかの要件エンニーリングとソフトウェアアーキテクチャの本を読みましたが、それらはすべて詳細と実装に集中しすぎています。私は本当にAPI /インターフェースを介して提供される機能にのみ関心があり、UML図などは私にとって正しい選択だとは思いません。現在収集した要件はユーザーストーリーとして説明できると思いますが、高度な要件分析にはこれで十分ですか？たぶん私は「一段深く」行かなければならない...

Documenting Software Architectures、second edition：Views and Beyond、Chapter 7：Documenting Software Interfaces をお読みください。

または、少なくともGoogle（マップ、GData-古いが複雑）、Amazon（S3）などのよく知られているAPIドキュメントを確認するか、MSDNにまとめられたMicrosoftアプリケーションおよびサービスのドキュメントを調べます（Liveサービスの場合、Windowsの場合も）。

通常、APIドキュメントには3つの部分があります。

• 物事の目的、誰かがそれから何を作ることができるか、おそらく建築の概要
• 通常はコードサンプルとダウンロード可能なサンプルアプリケーションを使用して、APIでのいくつかの一般的なタスクを説明する開発者ガイド。
• 動作方法のAPIリファレンス

理論的には-BrookのMythical Man Monthを信じるなら-あなたはドキュメントを設計し、一致する実装があることを確認します。

今練習に戻って

APIの設計要件は、他のソフトウェア設計と同じです。

1. APIを使用するさまざまなアクター（たとえば、コンテキスト図を使用）に参加します。
2. システムの各アクターの典型的なニーズをユースケースとともに詳述します
3. ユースケースごとに、想像上のシステムの使用方法に関する一連のシナリオを作成します（「効果的なユースケースを書く」という本が役立つかもしれません）。
4. ロバストネスダイアグラム、シーケンスダイアグラム、またはアクティビティダイアグラムのいずれかを作成しますが、 どのメッセージを渡す必要があるかを理解するために、シナリオに基づいて動作を設計します
5. メッセージから、各メッセージが正常に通信されるために必要なパラメーターを調べることにより、基礎となるデータアーキテクチャを推定します。

多くの人は基礎となるデータ構造から始めますが、それはばかげていると思います。コンピューター（およびオブジェクト）は相互作用に関するものです。正常な対話を実行するには、どちら側から何を通信する必要があるかを理解する必要があります。データはそれらの相互作用のパラメーターにすぎません。

私は通常、渡された引数をオブジェクトまたはクラスとして表示するアクティビティ図または単純なフローチャートを実行します。つまり、進行中の制御フローがありますが、一方の当事者が他方にどの情報を渡したかがわかります。

後はあなたがこれらすべてを終え、あなたはつかむシナリオを再び、そしてクラフトを開始受け入れテスト。これは、APIがコンピュータークライアントで使用されるためです。したがって、最初のコードは、テストとして自動取得を実行するコンピュータークライアントである必要があります。

受け入れテストは、「提供された入力」-「期待される出力」の形式で、またはコードとして記述されます。BDDとTDDに関する本はたくさんあり、優れたテストの書き方を説明しています。

また、テストは初日から実行可能でなければならないため、Web APIを構築している場合に備えて、RESTインターフェースなどについての本を発表し始めます。

シナリオから、サンプルコードと開発者ガイドも作成します。

シーケンス図とデータアーキテクチャ図から、APIリファレンスを作成します。

HTMLを少し追加して、すべてのテストに合格し、アプリケーションが高速、安全、かつ十分に堅牢であることを確認して、それを使い始めましょう！

（私は知っています、これは滝っぽいものでした：アジャイルも同じですが、常にこれのごく一部、たとえばスプリントごとにいくつかのシナリオを行うだけです）

あなたは本当にあなたが持っているものよりも「フォーマル」を取得する必要はありません。あなたは人間が読むために、そしておそらくほとんどが自分自身のためにそれを書いているので、それを覚えておいてください。私の提案の1つは、階層に配置し、アウトライン形式で番号を付けることです。このように、レビュー、チェックリストなどでは、3.0.1のような番号を省略形として参照し、話していることを簡単に明確にすることができます。