タグ付けされた質問 「api-design」

この記事の著者は、 時には、本質的にRESTfulではない操作をAPIで公開する必要があります。 そしてそれ APIのアクションが多すぎる場合は、RESTful原則を使用するのではなくRPCの観点で設計されているか、問題のAPIがRPCタイプモデルにより適していることを示しています。 これは、他の場所でも読んだり聞いたりしたことを反映しています。 しかし、これは非常に紛らわしいと思うので、問題をよりよく理解したいと思います。 例I：RESTインターフェースを介してVMをシャットダウンする VMのシャットダウンをモデル化するには、根本的に異なる2つの方法があると思います。それぞれの方法にはいくつかのバリエーションがありますが、ここでは最も基本的な違いに集中しましょう。 1.リソースの状態プロパティにパッチを適用します PATCH /api/virtualmachines/42 Content-Type:application/json { "state": "shutting down" } （または、PUTサブリソース上/api/virtualmachines/42/state。） VMはバックグラウンドでシャットダウンし、シャットダウンが成功するかどうかに応じて、後のある時点で状態が「電源オフ」で内部的に更新される可能性があります。 2.リソースのアクションプロパティのPUTまたはPOST PUT /api/virtualmachines/42/actions Content-Type:application/json { "type": "shutdown" } 結果は、最初の例とまったく同じです。状態はすぐに「シャットダウン」に更新され、最終的には「電源オフ」に更新されます。 どちらのデザインもRESTfulですか？ どちらのデザインが優れていますか？ 例II：CQRS 複数の集約の更新につながる可能性のある、または具体的なリソースとサブリソースのCRUD操作にマッピングできない「アクション」（別名コマンド）が多数あるCQRSドメインがある場合はどうなりますか？ 具体例で可能な限り多くのコマンドを具体的なリソースで作成または更新し（例Iの最初のアプローチに従って）、残りの部分に「アクションエンドポイント」を使用してみてください。 または、すべてのコマンドをアクションエンドポイントにマッピングする必要があります（例Iの2番目のアプローチのように）。 どこで線を引きますか？設計のRESTful性が低下するのはいつですか？ CQRSモデルは、APIのようなRPCにより適していますか？ 上記の引用テキストによると、私が理解しているとおりです。 私の多くの質問からわかるように、このトピックについて少し混乱しています。それをよりよく理解するのを手伝ってもらえますか？

24 rest  domain-driven-design  api-design  cqrs 

リソースを持つWebアプリケーションと、別の同様のリソースを持つリモートアプリケーションへの参照があるシステムを想定して、「ローカル」リソースを「リモート」リソースと同期する双方向同期アクションをどのように表現しますか？ 例： ToDoリストを表すAPIがあります。 GET / POST / PUT / DELETE / todos /など そのAPIは、リモートTODOサービスを参照できます。 GET / POST / PUT / DELETE / todo_services /など APIを介してプロキシ経由でリモートサービスから仕事を操作できます GET / POST / PUT / DELETE / todo_services / abc123 /など TodoのローカルセットとTODOSのリモートセット間で双方向の同期を行う機能が必要です。 ある種のRPCでは、次のことができます POST / todo_services / abc123 / sync / しかし、「動詞は悪い」という考えでは、このアクションを表現するより良い方法はありますか？

23 api  rest  api-design  synchronization 

私は実用的なREST APIを設計していますが、既存のエンティティをコレクションに追加する最善の方法に少し立ち往生しています。私のドメインモデルには、サイトのコレクションを持つプロジェクトが含まれています。これは厳密な多対多の関係であり、関係を明示的にモデル化するエンティティ（ProjectSiteなど）を作成する必要はありません。 私のAPIにより、消費者は既存のサイトをプロジェクトに追加できます。ハングアップしているのは、本当に必要なデータはProjectIdとSiteIdだけだということです。私の最初のアイデアは： 1. POST myapi/projects/{projectId}/sites/{siteId} しかし、私も考えました 2. POST myapi/projects/{projectId}/sites JSONコンテンツとして送信されるSiteエンティティを使用します。 オプション1はシンプルで機能しますが、あまり適切ではないため、このパターンに従うことができない他の関係があるため、APIに矛盾が生じます。 オプション2は良い感じですが、2つの懸念につながります。 新しいサイトが投稿された場​​合（SiteId = 0）、サイトを作成するか、例外をスローする必要がありますか？ 関係を作成するためにProjectIdとSiteIdのみが必要なため、他のプロパティのデータが間違っているか、欠落しているサイトが投稿される可能性があります。 3番目のオプションは、関係を作成および削除するためだけに単純なエンドポイントを提供することです。このエンドポイントでは、ProjectIdとSiteIdのみを含むJSONペイロードが必要です。 どう思いますか？

23 rest  api-design 

ファイルをアップロードする関数であるAPIを作成しています。ファイルが正しくアップロードされた場合、この関数は何も/ voidを返さず、何らかの問題が発生したときに例外をスローします。 なぜ偽りではなく例外なのか？例外の内部で、失敗の理由（接続なし、ファイル名の欠落、パスワードの誤り、ファイルの説明の欠落など）を指定できるためです。カスタム例外を作成したかった（APIユーザーがすべてのエラーを処理するのに役立つ列挙型を使用）。 これは良い習慣ですか、それともオブジェクトを返す方が良いですか（内部にブール値、オプションのエラーメッセージ、エラーの列挙を含む）？

22 java  api-design  exceptions  functions  architectural-patterns 

最近、私は自分のAPIを開発しており、そのAPI設計への投資に興味を持ち、API設計を改善する方法に強い関心を持っています。 数回登場した側面の1つは（私のAPIのユーザーによるものではなく、トピックに関する私の観察中の議論による）です。 たとえば、談話レポについてはGitHubでのこの議論を参照してください。 foo.update_pinned(true, true); （パラメータ名、ドキュメントなどを知らずに）コードを見るだけでは、何をしようとしているのか推測できません。2番目の引数はどういう意味ですか？推奨される改善策は、次のようなものにすることです。 foo.pin() foo.unpin() foo.pin_globally() そして、それは物事を明確にします（2番目の引数はfooをグローバルに固定するかどうかでした、私は推測しています）、この場合、後者は確かに改善されることに同意します。 ただし、コードを見ただけでは何をしているのかわからない場合でも、異なるが論理的に関連する状態を設定するメソッドが、個別のメソッド呼び出しではなく、1つのメソッド呼び出しとしてより適切に公開される場合があると思います。（したがって、パラメータ名とドキュメントを調べて調べる必要があります-個人的には、APIに不慣れな場合は常に何をしてもかまいません）。 たとえばSetVisibility(bool, string, bool)、FalconPeerで 1つのメソッドを公開し、次の行を確認するだけです。 falconPeer.SetVisibility(true, "aerw3", true); あなたはそれが何をしているのか分からないでしょう。falconPeer論理的な意味での「可視性」を制御する3つの異なる値を設定しています。パスワードのみで参加要求を受け入れ、検出要求に応答します。これを3つのメソッド呼び出しに分割すると、APIのユーザーは、「可視性」のすべての側面を設定するために1つのメソッドを公開するだけで他のユーザーに設定を忘れさせる「可視性」の側面を設定することになります。さらに、ユーザーが1つのアスペクトを変更する場合、ほとんどの場合、別のアスペクトを変更する必要があり、1回の呼び出しで変更できます。

20 programming-practices  naming  api  api-design 

OSの本で、「パブリックAPIは永遠に存在します。それを正しく実現するチャンスは1つだけです」と読みました。本当ですか？オペレーティングシステムのAPIまたは他のAPIにも適用できますか？たとえば、これはTasker、Locale、PushoverなどのAndroidアプリケーションのAPIに当てはまりますか？

20 android  api  api-design 

閉じた。この質問は意見に基づいています。現在、回答を受け付けていません。 この質問を改善したいですか？この投稿を編集して事実と引用で答えられるように質問を更新してください。 5年前に閉鎖されました。 これは、java.util.Listなどの順序付きコレクション用です。言語設計者が最後のメソッドを含めなかったのはなぜですか？私が考えることができる唯一の理由は次のとおりです。 コレクションが空の場合のあいまいさ（nullを返すか、例外をスローします） APIの膨張 他の理由は？

19 java  api-design 

多数のデータベース抽象化レイヤーにさらされた後、私は、データにアクセスするための独自の異なるパラダイムを発明するすべてのライブラリーのポイントが何であるか疑問に思い始めています。新しいDALを取得することは、新しい言語をもう一度学習するように感じます。通常、やりたいことは、既に自分の頭に書いたSQLクエリを出力するようにレイヤーを説得することだけです。 そして、それは事後の読みやすさにさえ触れていない： # Exhibit A: A typical DAL rows = db(db.ips_x_users.ip_addr == '127.0.0.1') .inner_join(db.ips_x_users.user_id == db.users.id) .select(order=(db.ips_x_users.last_seen, 'desc'), limit=10) # Exhibit B: Another typical DAL rows = db.ips_x_users .join(db.users, on=db.ips_x_users.user_id == db.users.id) .filter(db.ips_x_users.ip_addr == '127.0.0.1') .select(sort=~db.ips_x_users, limit=10) # Exhibit C: A hypothetical DAL based on standard SQL syntax rows = …

18 database  sql  api-design  dsl 

モバイルアプリで使用されるeコマースWebサイト用のRest APIを開発しています。 アプリのホームページでは、スライダー、トップブランド、ベストセラー製品、トレンド製品などの複数のリソースを呼び出す必要があります。 API呼び出しを行うための2つのオプション： シングルコール： www.example.com/api/GetAllInHome 複数の呼び出し： www.example.com/api/GetSliders www.example.com/api/GetTopBrands www.example.com/api/GetBestSellingProducts www.example.com/api/GetTrendingProducts 残りのAPI設計に最適なアプローチはどれですか。単一呼び出しか複数呼び出しか、長所と短所を説明してください。 どちらがリクエストに応答するのに時間がかかりますか？

18 rest  api  api-design  url 

Javaデザイナーがjava.lang.Stringクラスで文字列操作メソッドの静的バージョンを作成しなかったのはなぜですか？以下のメソッドは私が参照するものですが、質問はクラス内の他の非静的メソッドにも拡張できます。 concat(String) substring(int, int) replace(char, char) toLowerCase() replace(CharSequence, CharSequence) toLowerCase(Locale) replaceAll(String, String) toString() replaceFirst(String, String) toUpperCase() split(String) toUpperCase(Locale) split(String, int) trim() substring(int) これらのメソッドの非静的バージョンのみを使用すると、そのようなメソッドを呼び出さなければならない場所で明示的な nullチェックが強制されます。たとえば、単に呼び出すexample = example.trim()と、NullPointerException ifになりString example = nullます。そのため、プログラマは次の定型的なヌルチェックを行う必要があります。 if (example != null) example = example.trim(); // OR: example = (example==null) ? null : example.trim(); example = (example==null) ? …

17 java  api-design  null 

私はc＃yield returnを使用して可愛すぎるという興味深い記事を読みました IEnumerableが実際の列挙可能なコレクションであるか、またはyieldキーワードで生成されたステートマシンであるかを検出する最良の方法は何なのかと思いました。 たとえば、（記事の）DoubleXValueを次のように変更できます。 private void DoubleXValue(IEnumerable<Point> points) { if(points is List<Point>) foreach (var point in points) point.X *= 2; else throw YouCantDoThatException(); } 質問1）これを行うより良い方法はありますか？ 質問2）これは、APIを作成するときに心配する必要があるものですか？

17 c#  api-design 

私は模倣Aに設計された内部ライブラリを使用しているC ++ライブラリを提案し、いつか過去数年間で、私はそのインターフェースが使用してから変更を参照std::stringしますstring_view。 そこで、新しいインターフェースに適合するようにコードを忠実に変更しました。残念ながら、私が渡さなければならないのは、std :: stringパラメーターと、std :: string戻り値です。そのため、私のコードは次のように変更されました。 void one_time_setup(const std::string & p1, int p2) { api_class api; api.setup (p1, special_number_to_string(p2)); } に void one_time_setup(const std::string & p1, int p2) { api_class api; const std::string p2_storage(special_number_to_string(p2)); api.setup (string_view(&p1[0], p1.size()), string_view(&p2_storage[0], p2_storage.size())); } 私は、この変更がAPIクライアントとして私に何を買ったのか、実際には、コードを増やすこと以外は見当たらないでしょう（おそらく失敗するためです）。API呼び出しの安全性は低下し（APIがパラメーターのストレージを所有しなくなったため）、おそらくプログラム0の作業を節約しました（コンパイラーができる最適化の移動により）。起動後またはどこかで大きなループで行われない、または行われない割り当てがいくつかあります。このAPI用ではありません。 ただし、このアプローチは、他の場所で見られるアドバイス、たとえば次の回答に従うようです。 余談ですが、C ++ 17以降では、std :: string_viewを優先してconst std :: …

16 c++  api-design  strings 

ユーザーとリンクの2つのリソースがあります。 ユーザーは複数のリンクを関連付けることができます。次のURIでユーザーに関連付けられたリンクにアクセスできるように、RESTful APIを設計しました。 /users/:id/links ただし、常にリンクだけのURIが必要です。ユーザーに関係なく、すべてのリンクが必要な場合があります。 このために私は： /links これは大丈夫ですか？リンクに2つのURIがありますか？ 代わりに、次のようなURIを使用してユーザーのリンクにアクセスする必要があるかどうか疑問に思います。 /links/user/:id または /links/?user=:id この方法では、リンク用のリソースは1つしかありません。

16 api  rest  api-design 

URLのREST APIのバージョンを指定することは非常に一般的です。具体的には、パスの先頭、つまり次のようなものです。 POST /api/v1/accounts GET /api/v1/accounts/details ただし、バージョンが各APIに関連付けられているデザインは見ていません。つまり、各APIのバージョンを個別に管理します。すなわち： POST /api/accounts/v2 GET /api/accounts/details/v3 このアプローチを使用すると、破壊的な変更が必要なときに特定のAPIのAPIバージョンをインクリメントします。API全体のバージョンをインクリメントする必要はありません。 一般的なスタイルの代わりにこのスタイルを使用することの欠点は何ですか？

15 rest  api-design  versioning  enterprise-architecture  engineering 

主に単一のクライアントのニーズを満たすことを目的としたRESTful APIを設計しています。非常に特殊な状況のため、このクライアントはできるだけ少ないリクエストを作成する必要があります。 APIは、リクエストのAccept-Languageヘッダーを介してi18nを処理します。これは、利用可能なすべてのロケールで単一のエンドポイントへの要求の応答をクライアントが保存する必要がある1つの機能を除き、クライアントが行う必要があるすべてのことに対して機能します。 クライアントが単一のリクエストでこれらすべての情報を取得できるように、一貫性のある適切に構造化されたRESTful API設計を壊さずに、何らかの方法でAPIを設計できますか？ これまで検討してきたオプション： Accept-Languageヘッダーに複数のロケールを含めることを許可し、応答で要求されたすべてのロケールのローカライズバージョンを追加します。各ロケールはキーとしてISO 639-1言語コードで識別されます。 そのエンドポイントに「？all_languages = true」パラメーターのようなものを作成し、そのパラメーターが存在する場合、応答で使用可能なすべてのロケールのローカライズバージョンを返します。 （上記のいずれも機能しない場合）ローカライズされたすべてのバージョンをクライアントから取得するために複数のリクエストを作成します。 どれが最良の選択肢ですか？

15 rest  api  api-design  http