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

指定された開始日と終了日に基づいて、合計金額を月額に分割するAPI関数があります。 // JavaScript function convertToMonths(timePeriod) { // ... returns the given time period converted to months } function getPaymentBreakdown(total, startDate, endDate) { const numMonths = convertToMonths(endDate - startDate); return { numMonths, monthlyPayment: total / numMonths, }; } 最近、このAPIの消費者は、1）終了日ではなく月数を提供するか、2）毎月の支払いを提供して終了日を計算することにより、他の方法で日付範囲を指定したいと考えました。これに応じて、APIチームは機能を次のように変更しました。 // JavaScript function addMonths(date, numMonths) { // ... returns a new date …

38 api-design 

私は、多くの問題に苦しんでいる非常に貧弱に設計されたソフトウェアプロジェクトへの変更を提案しています。高レベルでは、プロジェクトはフロントエンドでAngularを利用し、さまざまなREST APIを使用します。それはすべて素晴らしいことです（私たちの技術やツールを変更する必要はありません）。問題は、コードベースがUIでサーバー側のAPIよりも不均衡に大きいことです。ビジネスロジックの多くはUIに存在し、REST APIはUIレイヤーへの単純なCRUDデータベースインターフェイスです。 たとえば、顧客へのPOSTは顧客レコードを作成し、PUTはその顧客を変更します。それ以上でもそれ以下でもありません。ただし、ビジネスロジックはそれよりも要求が厳しくなります。顧客を作成する一般的なプロセスは、1つのデータベースレコードを挿入するだけではありません。他の必要なテーブルにデータをプロビジョニングし、特定の検証と計算などを実行します。この動作のすべてをカプセル化する単一のPOST / PUT呼び出しを行い、消費クライアントの負荷を軽減します。 したがって、私の視点では、この包括的なオーケストレーションはUIではなくサーバー（フルコントロール、ログなど）上に存在する必要がありますが、1つの反論は、このアプローチはRESTfulではなくなるということです。したがって、既存の技術スタックを継続することを推奨するが、コードが属する場所で基本的なシフトを実装することが推奨される場合、このアプローチをどのように説明するのが最適かはわかりません。

37 rest  api-design  enterprise-architecture 

JSON APIに関しては、応答をフラット化し、ネストされたJSONオブジェクトを避けるのが良いでしょうか？ 例として、IMDbに似ているがビデオゲーム用のAPIがあるとします。いくつかのエンティティ、Game、Platform、ESRBRating、GamesとPlatformsをマップするGamePlatformMapがあります。 ID 1のゲームを取得する/ game / 1をリクエストすると、プラットフォームとesrbRatingがネストされたゲームオブジェクトを返します。 { "id": 1, "title": "Game A", "publisher": "Publisher ABC", "developer": "Developer DEF", "releaseDate": "2015-01-01", "platforms": [ {"id":1,"name":"Xbox"}, {"id":2,"name":"Playstation"} ], "esrbRating": { "id": 1, "code": "E", "name": "Everyone" } } JPA / Hibernateのようなものを使用している場合、FETCH.EAGERに設定されていれば自動的にこれを行うことがあります。 もう1つのオプションは、単にAPIを追加して、エンドポイントを追加することです。 その場合、/ game / 1が要求されると、ゲームオブジェクトのみが返されます。 { "id": 1, "title": "Game …

37 design  rest  api-design  json 

HTTP API応答に関する何らかの標準はありますか？ この談話スレッドを読んだ後、私は疑問に思い始めました。私の仕事ではパブリックHTTP JSON APIを開発していますが、厳密に必要でない場合は何も返しません（たとえば、/ resource / {id}へのPUTは、OKまたは対応する4XXまたは5XXコードのときに200のみを返しますが、 JSON本体） {"success":true}上記のリンクで説明したようなジェネリックを返す必要がありますか、それとも「void」ボディを返してすべてをhttp応答コードで処理しても大丈夫ですか？

33 rest  api-design  http 

静的メソッドとインスタンスメソッドに関する議論Sqrt()では、静的メソッドではなく、数値型のインスタンスメソッドである必要があると常に考えています。何故ですか？それは明らかに価値に作用します。 // looks wrong to me var y = Math.Sqrt(x); // looks better to me var y = x.Sqrt(); 多くの言語にはインスタンスメソッドがあるので、値型にはインスタンスメソッドを含めることができますToString()。 コメントからいくつかの質問に答えるには：なぜ1.Sqrt()合法ではないのですか？1.ToString()です。 一部の言語では値型のメソッドを使用できませんが、一部の言語では使用できます。Java、ECMAScript、C＃、Python（__str__(self)定義済み）など、これらについて話します。同じことがceil()、floor()などの他の関数にも当てはまります。

31 programming-languages  language-design  history  api-design  math 

Micro-Servicesを使用してアプリケーションを設計していますが、複数のサービスからデータを収集するために使用する最適なメカニズムがわかりません。 私は2つのオプションがあると信じています： サービスが直接対話できるようにする「サービス間」通信メカニズムを統合します。API Gatewayは、統合された応答をAPI Gatewayに返す前に、個々のサービスを呼び出してから、他のサービスを呼び出してデータを収集します。その後、APIは呼び出し元に応答を返します。（これは、serviceBへの呼び出しがserviceAからの応答を必要とする場合、同期呼び出しである必要があります。IEは、個人とアドレスサービスを分離します。） API Gatewayで各サービスを直接呼び出し、応答を返す前にAPI内のデータを統合します。 サービスが相互に通信するとカップリングが導入されるため、2番目のオプションに傾いています。この場合、モノリシックアプリケーションを設計することもできます。ただし、このオプションを使用すると頭から離れて考えることができる重大な欠点がいくつかあります。 APIに複数のサービスへの複数の呼び出しを実行させると、特にそれらの呼び出しの一部がブロックしている場合に、APIサーバーの負荷が増加します。 このメソッドは、APIがアプリケーションが実行しようとしていることを「認識」する必要があることを意味します（IEロジックをAPIにプログラミングして、サービスの呼び出しを処理し、データを統合する必要があります）。マイクロサービスの愚かな「エンドポイント」として機能します。 この問題に対する標準的なアプローチが何であるか、そして私が見逃している別の3番目のオプションがあるかどうかを知りたいですか？

30 architecture  api-design  microservices 

現在公開APIが次のようになっているライブラリを評価しています。 libengine.h /* Handle, used for all APIs */ typedef size_t enh; /* Create new engine instance; result returned in handle */ int en_open(int mode, enh *handle); /* Start an engine */ int en_start(enh handle); /* Add a new hook to the engine; hook handle returned in h2 */ int …

27 c  api-design  libraries 

新しいウェブサイトでユーザー名を予約する必要があります。 これらは一般に3つのカテゴリに分類されます 1）誰も持ってはならないユーザー名（例：admin、user、service、help、rootなど） 2）彼らが現れるイベントで予約したい超有名人や会社の名前 3）当社が直接指定したその他の名前。 最初の2つのカテゴリのユーザー名のリストがどこかに存在し、それらを使用することができれば、本当に役立ちます。 誰もがそのようなリストを知っていますか？

26 database  design  data  api-design 

モノリシックREST APIをマイクロサービスアーキテクチャに移行することを検討していますが、データストレージについて少し混乱しています。私が見るように、マイクロサービスの利点のいくつかは次のとおりです。 水平方向にスケーラブル-負荷やサーバーのダウンに対処するために、マイクロサービスの複数の冗長コピーを実行できます。 疎結合-他のマイクロサービスを変更することなく、マイクロサービスの内部実装を変更できます。また、独立して展開および変更することもできます。 私の問題はデータストレージです。ご覧のとおり、いくつかのオプションがあります。 すべてのマイクロサービスで共有される単一のデータベースサービス-これは、疎結合の利点を完全に排除するようです。 各マイクロサービスにローカルにインストールされたデータベースインスタンス-これを水平方向にスケーリングする方法が見当たらないため、オプションとは思わない。 各マイクロサービスには独自のデータベースサービスがあります-疎結合と水平スケーリングの利点を保持するため、これは最も有望であると思われます（冗長データベースコピーの使用および/または複数でのシャーディング） 私には、3番目のオプションが唯一のオプションのように思えますが、私には信じられないほど重く、非常に過剰に設計されたソリューションです。私がそれを正しく理解している場合、4-5マイクロサービスを備えたシンプルなアプリケーションでは、16-20サーバーを実行する必要があります-マイクロサービスごとに2つの実際のマイクロサービスインスタンス（サーバー障害の場合、およびダウンタイムなしでデプロイするため）、およびマイクロサービスごとに2つのデータベースサービスインスタンス（サーバー障害などの場合）。 これは、率直に言って、少しばかげているようです。16〜20台のサーバーでシンプルなAPIを実行しますが、現実的なプロジェクトにはおそらく4〜5以上のサービスがあることに留意してください。これを説明する基本的な概念がありませんか？ 回答中に役立ついくつかのこと： 私はこのプロジェクトの唯一の開発者であり、近い将来になります。 Node.jsとMongoDBを使用していますが、言語に依存しない回答に興味があります。答えは、間違ったテクノロジを使用しているだけかもしれません。

25 architecture  rest  api-design  microservices 

RESTful APIの作成中、同じURLでHTTP動詞を使用する必要がありますか（可能な場合）、またはアクションごとに特定のURLを作成する必要がありますか？ 例えば： GET /items # Read all items GET /items/:id # Read one item POST /items # Create a new item PUT /items/:id # Update one item DELETE /items/:id # Delete one item または、次のような特定のURLを使用します。 GET /items # Read all items GET /item/:id # Read one item POST /items/new # …

25 rest  api-design  web-api 

現在のプロジェクトでは、JSONのみをサポートするものとして文書化されている、新しく作成されたRESTful APIの使用を伴うサービスの実装を担当しています。 クライアントは、一貫して「application / json」のacceptヘッダーと「application / json」のcontent-typeで要求を行います。ただし、一部のエンドポイントは、HTMLのコンテンツタイプ、さらにはHTML本文で応答を送信します。私にとってこれは明らかに間違ったアプローチであり、正当化することはできません。 プロジェクト全体を通して、この同じプラクティスが2つの異なるベンダーと2つの異なるサービスに適用されています。サービスを変更する必要がある理由を正当化する必要があることに気づきました。ベンダーは、クライアントはこれに対処する必要があると述べており、デフォルトの「箱から出して」これに対処しないため、選択したRESTライブラリでさえ疑問視されています（RestEasy）。 これはフラストレーションの大きなポイントでした。私の主張を裏付ける多くの参考文献を見つけることができません。これは、それが非常に明白であるので、ポイントが議論の余地があるからだと思います。 問題は、何かが足りないということですか？私はこれについて熱心ですか？このシナリオでcontent-typeのapplication / jsonを持たないJSON APIを使用しても大丈夫ですか？参照をいただければ幸いです。商業的な観点からこの状況をどのように解決しますか？

25 rest  api-design  json  bad-code 

システム間で（ビジネスレベルで）APIについて議論するとき、チームには2つの異なる視点があります。一般的な抽象アプローチを好む人もいれば、そうでない人もいます。 例：単純な「個人検索」APIの設計。具体的なバージョンは searchPerson(String name, boolean soundEx, String firstName, boolean soundEx, String dateOfBirth) 具体的なバージョンを支持する人々は言う： APIは自己文書化されています わかりやすい 検証は簡単です（コンパイラーまたはWebサービスとして：スキーマ検証） キッス 私たちのチームの他のグループは、「これは単なる検索条件のリストです」と言うでしょう。 searchPerson(List<SearchCriteria> criteria) と SearchCritera { String parameter, String value, Map<String, String> options } おそらくいくつかの列挙型の「パラメータ」を作成します。 支持者は言う： API（の宣言）を変更することなく、実装は変更できます。たとえば、基準やオプションを追加します。展開時にそのような変更を同期しなくても。 具体的なバリアントでもドキュメントが必要です スキーマ検証は過大評価されており、多くの場合、さらに検証する必要があります。スキーマはすべてのケースを処理できません 別のシステムと同様のAPIが既にあります-再利用 反論は 有効なパラメーターと有効なパラメーターの組み合わせに関する多くのドキュメント 他のチームにとって理解するのがより難しいので、より多くのコミュニケーション努力 ベストプラクティスはありますか？文献？

25 api  web-services  api-design 

私が管理しているRailsプラットフォームがあります。その上に構築された多くの異なるWebアプリケーションがあります。ただし、現在、クライアントは、ユーザーがサイトにアクセスできるようにするためにAPIを要求していますが、自動化されたタスクの一部を利用しています。 このプラットフォームは、保険アプリケーションを構築するために使用され、オンラインでの購入を可能にし、保険契約に関連するドキュメントをダウンロードする方法を提供します。 APIを構築するときの私の質問は次のとおりです。 私は多くのことをしなければならない場合は、のようなvalidate、作成user、user profileおよびpolicy、ほとんど同時に。4つの別々のAPI呼び出しを行い、クライアントに4つの呼び出しをビルドさせる必要があります。または、多くのパラメータを除いて、クライアントを検証し、これらの3つすべてを同時に作成し、クライアントの物事を単純化する1つの呼び出しが必要ですか？ この場合、クライアントは必要な情報をすべて同時に取得するため、アプリケーションに自然なフローがあり、一時停止してプラットフォームにAPI呼び出しを行うことができないようです。 以前は多くのAPIを使用してクライアント側にいたことがありますが、私の直感は、クライアントにとってできるだけ単純にし、1回だけ呼び出しを行うことです。ただしfunctions、これによりAPI がかなり大きくなり、私もどちらのファンでもありません。 私はこれに取り組むことをどのように提案しますか？ 注として、私はクライアント側で複雑なAPIを実装する能力にあまり自信がありません。

25 web-applications  ruby-on-rails  api-design 

この質問は、Software Engineering Stack Exchangeで回答できるため、Server Faultから移行されました。 6年前に移行され ました。 私は現在、初めてのHTTP APIを実装しています。 適切な状況に適切なコードを実装することを決心しているため、HTTPステータスコードのウィキペディアページを見るのに多くの時間を費やしてきました。そのページには、420のコードがリストされています。これは、Twitterがレート制限に使用していたカスタムコードです。 ただし、すでにレート制限のコードがあります。429です。 これにより、ユースケースが既に存在するのに、なぜカスタムに設定するのか疑問に思いました。それはただかわいいだけですか？もしそうなら、異なる状況コードを返すことがどのような状況で受け入れられるようになりますか？また、クライアントに問題がある場合はどうなりますか？ Mozillaがジョーク418: I’m a teapot応答を実装していないことをどこかで読んだので、クライアントは実装するステータスコードを選択すると思います。それが本当なら、Twitterの面白おかしい小さなコードがあなたの落ち着いたコードの問題を改善していると想像できます。 誤解しない限り、任意のコード番号を使用して好きなものを意味することができます。この規約では、404が見つからないことを意味し、429は簡単にすることを意味します。

24 api-design  http 

ユーザーが常にいくつかの「プラン」のいずれかを使用するプロジェクト用のREST APIを設計しています。各プランは、アカウントに含めることができるユーザーの最大数やアップロードできるデータの最大数など、リソースの制限を定義します。これらの制限の1つに達すると、ユーザーはプランをアップグレード（基本的に支払い）して、より多くのリソースを取得できます。 アカウントのリソース制限のためにアクションを実行できない状況を示す特別なステータスコードを返します。プランをアップグレードすると解決します-たとえば、ユーザーがストレージ容量の100％を使用して追加のファイルをアップロードしようとした場合、彼らはこの応答を受け取ります。 候補者は次のとおりです。 403 Forbidden -ただし、このケースと、ユーザーがこのアクションを実行するための許可を単に持たない他のケースとを区別したいと思います。 401 Unauthorized -良いアイデアではありません。認証関連の問題にこれを使用しています。 402 Payment Required -ある意味理にかなっていますが、標準ではないが予約済みのステータスコードの使用が心配です 423 Locked将来的には他のものに使用する可能性が低いため、さらに標準以下のもの 別のオプションは、非常に標準的なもの403を使用することです。ただし、応答本文にエラーの詳細を示します。 どのアプローチが（a）長期的に最も効果的であり、（b）RESTfulな原則にもっとうまく適合すると信じているのか疑問に思っています。

24 rest  api-design  http