APIを作成するとき、小さな関数と多くの呼び出し、またはいくつかの呼び出しと大きな関数に固執する必要がありますか？

私が管理しているRailsプラットフォームがあります。その上に構築された多くの異なるWebアプリケーションがあります。ただし、現在、クライアントは、ユーザーがサイトにアクセスできるようにするためにAPIを要求していますが、自動化されたタスクの一部を利用しています。

このプラットフォームは、保険アプリケーションを構築するために使用され、オンラインでの購入を可能にし、保険契約に関連するドキュメントをダウンロードする方法を提供します。

APIを構築するときの私の質問は次のとおりです。

私は多くのことをしなければならない場合は、のようなvalidate、作成user、user profileおよびpolicy、ほとんど同時に。4つの別々のAPI呼び出しを行い、クライアントに4つの呼び出しをビルドさせる必要があります。または、多くのパラメータを除いて、クライアントを検証し、これらの3つすべてを同時に作成し、クライアントの物事を単純化する1つの呼び出しが必要ですか？

この場合、クライアントは必要な情報をすべて同時に取得するため、アプリケーションに自然なフローがあり、一時停止してプラットフォームにAPI呼び出しを行うことができないようです。

以前は多くのAPIを使用してクライアント側にいたことがありますが、私の直感は、クライアントにとってできるだけ単純にし、1回だけ呼び出しを行うことです。ただしfunctions、これによりAPI がかなり大きくなり、私もどちらのファンでもありません。

私はこれに取り組むことをどのように提案しますか？

注として、私はクライアント側で複雑なAPIを実装する能力にあまり自信がありません。

両方やってみませんか？システムの機能を公開する「低レベル」（いわば）APIと、クライアントが実行したいサービスを公開する別の「レイヤー」を用意します。この層は、必要な低レベルAPIを使用しますが、クライアントが必要とする場合、それらは引き続き公開されます。

更新：他の人が行ったすばらしい点やコメントの一部を含めること。

1. クライアントがより小さいAPIメソッドの1つを呼び出す必要があるかどうかを検討します。たとえば、createUserを呼び出さずにcreateUserProfileを呼び出すことは可能ですか？そうでない場合は、そのメソッドを公開しないでください。ありがとうNoobsArePeople2

2. シンプルだが優れた点。APIで何かを公開する際の重要なポイント-これを公開解除することはできません。機能するために必要な最小限を公開してから、すべてを公開するのではなく拡張します...そして、その裸で変更を加えることは恥ずかしくて厄介です。ありがとうMichaelT

あなたは間違った方法でそれを見ていると思います。大規模を心配しないでください| 小規模な通話または多数の| いくつかの呼び出し。

|で実行できるビジネスオブジェクトとアクションについて考えてください。のために| それらのオブジェクトに対して。

あなたが持っている：

• ユーザー
• ポリシー
• 料金
• ...

したがって、これらのオブジェクトの周りにAPI呼び出しを作成する必要があります。

• User.Create
• User.UpdatePassword
• Policy.Validate
• ...

アイデアは、ビジネスオブジェクトとそのアクションに基づいて、アトミックまたはほぼアトミックな操作を作成することです。これにより、設計とコーディングが簡素化されます-メンタルモデルまたはプログラマの期待に一致する、ビジネスオブジェクトが行うべきことを行う呼び出し。プログラマーまたはアーキテクトがビジネスアナリストと要件について議論している場合、全員が同じ用語と操作の一般的なフローを使用できます。

より大きなオールインワンタイプの呼び出しの問題は、副作用のリスクです。Policy.CreateがUserを生成し、他のアクションをトリガーする場合、プログラマーの期待を破ります。同様に、多くの小さな呼び出しにより、プログラマーはAを呼び出し、次にBを呼び出し、次にCを呼び出して、「単一の」ビジネス操作を実行することを忘れないようにします。

また、呼び出しに名前を付ける方法は、RailsおよびサポートするWebサービスがサポートするものに基づきます。

より規範的にするために、これはいくつかのパラメーターをとるいくつかの呼び出しを作成し、クライアントに見えないようにバックエンドで複数の呼び出しを行う場合があります。また、APIが基礎となるルーチンのラッパーにすぎない、かなり迅速で単純な呼び出しも行われます。

あなたの直感は正しいと思います-消費者にとってAPIをシンプルにします。ある程度、これが消費者主導契約の背後にある哲学です。

より具体的には、APIは適切なビジネスユースケースを公開する必要があります。手元のビジネスドメインを考慮してください。これらの低レベルの機能が本当に必要なのでしょうか。それらをカプセル化することの欠点は何ですか？APIの大規模な機能自体は問題ではありません。問題となるのは、消費者の介入を可能にするために大規模な関数がパーティション化される必要がある操作をシーケンスする場合です。

個人的には、次のAPIが好きです。

1. 一般的なユースケースを簡単に実行できるように最適化されています
2. CRUD操作に関連する呼び出しはバッチ指向であるか、バッチバージョンがあります
3. リフレクションを許可します（他のコンピューター言語のプラグインまたはバインディングを作成する人がプロセスを自動化できるように）