web-dev-qa-db-ja.com

APIを作成するとき、小さな関数と多数の呼び出し、または少数の呼び出しと大きな関数を使用する必要がありますか？

私はRails私が維持しているプラ​​ットフォームを持っています。それはその上に構築された多くの異なるWebアプリケーションを持っています。しかし、今、クライアントはサイトでユーザーを維持できるようにAPIを求めています、しかし私たちが持っている自動化されたタスクのいくつかを利用します。

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

したがって、APIを作成するときの私の質問は次のとおりです。

validateのような多くのことを行う必要がある場合は、user、user profile、およびpolicyをほぼ同時に作成します。 4つの個別のAPI呼び出しを行い、クライアント側で4つの呼び出しを作成する必要があります。 OR多くのパラメーターを除いて、クライアントを検証し、これら3つすべてを同時に作成して、クライアントの処理を簡略化する1つの呼び出しを行う必要がありますか？

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

以前はクライアント側で多くのAPIを使用していたので、私の根本は、それをクライアントにとって可能な限りシンプルにして、1回の呼び出しだけを行わせることです。ただし、これによりAPIでfunctionsがかなり大きくなり、私はどちらのファンでもありません。

これに取り組むにはどうすればいいですか？

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

web-applicationsruby-on-railsapi-design
25
Ryan

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

更新：他の人から寄せられた優れた点やコメントの一部を含めること。

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

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

32
dreza

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

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

あなたが持っています：

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

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

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

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

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

また、通話の名前の付け方は、Railsに基づいており、サポートするWebサービスがサポートします。

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

10
user53019

あなたの直感は正しいと思います。消費者にとってAPIをシンプルにしてください。ある程度、これは Consumer Driven Contracts の背後にある哲学です。

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

4
eulerfx

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

  1. 一般的な使用例を簡単に実行できるように最適化されている
  2. [〜＃〜] crud [〜＃〜] に関連する呼び出しは、バッチ指向であるか、バッチバージョンがある
  3. 許可 リフレクション （他のコンピューター言語用のプラグインやバインディングを書いている人はプロセスを自動化できます）
3
Paulo Scardine