APIビジネスロジックの意図された操作を開発者とビジネス関係者の両方に伝達する
現在、開発者のチームが最終的に構築する（RESTful）APIの意図された操作を設計しています。入力が出力に正しくマップされている限り（そしてデータベース内のデータが台無しにならない限り:-)）、実装の詳細には関心がありません。私にとっては、たとえばOOPまたはFPの方法で構築されているかどうかは重要ではありません。
問題：ビジネスの人々が何が起こっているのかを理解できるように（そしてうまくいけばフィードバックを提供できるように）、APIの意図された内部の仕組み/ビジネスロジックを伝達し、開発者が次のものを書くことができるようになります。本来あるべきことをします。したがって、かなり抽象的である必要がありますが、それでも開発者にとって十分な詳細が含まれている必要があります。
仕様は主に開発者が使用することを目的としています。ビジネスの人々はそれらを理解できるはずですが、開発者が構築を開始するのに十分な情報が含まれていることが重要です。
どうしても、各ユーザーインタラクション（またはAPIエンドポイント）を個別に説明することは理にかなっていると思います。これらは大まかに次の形式で説明できます。
- 説明（例：「ユーザーアカウントの作成」）
- 入力パラメータ（ユーザーが提供するデータ、例：「名前」、「電子メール」、「パスワード」）
- プロセス（内部の仕組みと結果のある種の表現）
理にかなっていますか？ここで重要なものが不足していますか？
プロセスを表すのに最も適した形式は何ですか？
擬似コードは、ビジネスマンにとってあまり意味がありません。自動化されたテストは作成され（開発者が使用します）、ビジネススタッフはそれを読みません。
現在、私はフローチャートに傾いています。それらは本質的に視覚的であり、うまく行えば理解するのに十分簡単であり、必要な量の詳細（条件など）を含めることができます。 Confluence（ドキュメントシステム）に保存されるERDのエンティティと属性を参照することもできます。注釈は、追加の（技術的な）詳細を提供するために使用できます。
これは合理的なアプローチですか？この状況でフローチャートはまともな解決策ですか？より良いオプションはありますか？
APIの機能を説明するための正しい、または「最良の」手段は、特定の機能に依存します。これに対する単純で頭の痛い「万能」ソリューションはありません。
一部の機能では、フローチャートが適切なオプションになる場合があります。一部の人にとっては、データフロー図の方が良いかもしれません。 「入力、処理、出力」の観点からプロセスの説明を整理することは非常に古いですが、それでも非常に効果的な手法です。いくつかの側面では、例の代表的な選択が最も役立ちます-後者は「ユーザーストーリー」にラップすることもできます。また、属性（および場合によってはデータ型）を持つテーブルも、開発者やトレーニングを受けたユーザーにも理解されます。一部のユーザーはERモデルを理解している場合もあります（ただし、正規化は複数のユーザーにとって既に技術的すぎる場合があります）。
"ドメイン駆動設計" は、 ユビキタス言語 、あいまいさが少なく、ユーザーにとって明確なセマンティクスを持つ言語を作成することで問題にアプローチしようとしますおよび開発者- DDDを実行しているかどうかにかかわらず、これは特定のドメインにとっても良い考えです。
しかし、最終的には、機能を正確に記述し、聴衆にとって適切なレベルの抽象化を見つけ、あまりにも粗雑で形式的でもない自然言語を使用するには、数年の経験が必要です。これは、本やこのサイトの回答から学ぶことはできないので、練習する必要があります。
これをほとんど忘れてしまいました-JoelSpolskyが18年前にNiceのブログ投稿を書いています 機能仕様の書き方 。それはおそらく、あなたが求めたものの良い例でしょう。彼の紹介を引用するには：
機能仕様は、ユーザーの観点から製品が完全に動作する方法を説明します。実装方法は関係ありません。機能について話します。画面、メニュー、ダイアログなどを指定します。
したがって、「@ RobertHarveyもコメントに書いているように」「内部の仕組み」に集中することは避けてください。 howではなく、関数が行うwhatに焦点を当てます。
あなたはまだ開発者やアーキテクトのように考えており、ユーザー/プロダクトマネージャー/ビジネスアナリストのように考える必要があると思います。
ユーザーストーリーまたはユースケースの観点からAPIの動作を説明できますか？これらは技術的ではありませんが、正しく行うと大きな影響があります。