問題タブ [api-design]

私は現在 API を開発しています。私が決定したことの 1 つは、クライアントが検証などのために sig を付けてリクエストを送信する 1 つの gateway.cfm ページを作成し、ゲートウェイがリクエストを処理し、コンポーネントを呼び出して結果を返すことでした。必要です。

たとえば、gateway.cfm?component=getBooks&sig=232345343 は getbooks コンポーネントを呼び出し、JSON を返します。

セキュリティ上の問題を無視すると、すべてのリクエストが 1 つのページに送信されるため、この API のパフォーマンスは低下しますか? または、すべてのリクエストが同じページに送られるかどうかに関係なく、これは Web サーバーにとって重要ではありません。

また、これもSSLによって保護されます。

API バージョニングのベスト プラクティスを見てみましたか? 、しかし答えに確信が持てないので、より具体的な例でバージョン管理の部分をもう一度質問します。私は 2 つの URI を持っています (1 つは URI の一部としてバージョン管理があり、もう 1 つはバージョン管理なし):

最初のリンクが REST の考え方を表しているかどうか疑問に思っています。http://xxxx/v1/user/123いつかのようなより高いAPIバージョンがあることを示唆しているので、私は混乱していhttp://xxxx/v2/user/123ます。しかし、これは REST 用語では意味がありません。API バージョン自体は HTTP 1.0 または 1.1 であり、HTTP 要求内で既に送信されています。この REST リソース中心のビューは、SOAP や Java インターフェースなどの他の API インターフェースとは大きく異なります (修飾名で API バージョンを使用するのが一般的です)。

REST でバージョニングが意味を持つ唯一のことは、そのリソースの表現です (たとえば、新しいフィールドが追加または削除されます)。このバージョニングは、次のようなコンテンツ ネゴシエーションの部分に属します。

このようなバージョンのコンテンツ ネゴシエーションは、パス内の URI の一部である可能性があると主張することもできますが、同じリソースに対して異なる URI を使用することになり、ある時点でリダイレクトを維持する必要があるため、直観に反すると思います。

要約すると、REST URI には API のバージョン管理はなく、リソースの表現のバージョン管理のみが行われます。表現 version-info は content-negotiation に属します (queryParam または HTTP 'Accept' として)。

どう思いますか？どの点に反対/同意しますか?

C API 関数が出力を割り当てること、またはユーザーに出力バッファーを指定させることは良い考えですか? 例えば：

対

より具体的には、Win32 API が主に 2 番目のケース (たとえば、 GetWindowText、LookupAccountSid ) を使用する理由が気になります。API 関数が出力の大きさを知っている場合、なぜユーザーは出力サイズを推測しようとするのでしょうか? 2番目のケースが使用される理由に関する情報が見つかりません。

また、LookupAccountSid の例は特に悪いです。内部的には、呼び出し元に出力を割り当てる LSA API を使用します。次に、LookupAccountSid は、LSA から出力を返すことができる場合に、ユーザーにバッファーを割り当てます (そして、正しいバッファー サイズを推測します)。なんで？

ライブラリやAPIをうまく設計する方法についていくつか読んでいて、GoogleTechTalksでのJoshuaBlochのすばらしい講演に出くわしました。今、私はプロのAPI開発者にはほど遠いですが、同じものの大幅に縮小されたバージョンであるにもかかわらず、一連のクラス/関数のプログラミングは似ていると思います-アクションの明確な分離、使いやすさと楽しい使用、クリーンなコードの奨励、など。

私は広く使用されているオープンソースのJavaコードをいくつか調べていて、このアイデアを思いつきました（新しいことは何もありませんが、明快にそれを提示するだけです...）

擬似コード（またはBASICの方言） の例を見てみましょう。

Javaコードに触発されて、次のようなことができるようにしたいと思います。

私の質問はこれです：
他の誰かがこのような擬似コードから始まるAPIを設計しますか？

小さなものにいいアイデアですか？それぞれがおそらく10個のメソッドを持つ最大10個のクラスを言います。各メソッドは、その中に5〜6行以内のコードを記述します。これは明らかに、設計するクラスのサイズを示すための大まかな数値のセットです。完全なAPIに近いものではなく、趣味のプロジェクトだけではありません。小さなことを実行するが、それをうまく実行するプロフェッショナルパッケージです。

このアプローチに重大な欠点を見つけた人はいますか？

本当のメリットの1つは、最初にユースケースを書き留める必要があることだと思います。

もう1つは、名詞と動詞が単純なままであり、最終製品がMultiPhraseAbstractParadigmDesignPatternImplementor症候群を回避できるようにすることです:-D

以下のクラス定義を前提としています。スタブメソッドを静的にするか非静的にするかをどのように決定しますか？

これはちょっとした暴言ですが、非常に深刻な質問でもあります。jQuery は ajax パラメータのシリアル化を次のように変更しました。

jQuery 1.4 では、PHP で普及し、Ruby on Rails でサポートされているアプローチを使用して、jQuery.param でネストされたパラメーターのシリアル化のサポートが追加されています。たとえば、{foo: ["bar", "baz"]} は「foo[]=bar&foo[]=baz」としてシリアル化されます。

あなたはそれをキャッチしましたか？

パラメータを呼び出しますfoo。foo の値が配列の場合、jQuery はその名前をfoo[]背後に変更します。その理由は、一部の PHP 愛好家や Rubyist は、サード パーティの API が名前を変更することを期待しているためです。

古風な言い方をしますが、キーxで何かをマップに入れると、 の下に値が見つかると思いますx。または、少なくともオプションのオーバーライドを使用して、これをデフォルトの動作にします。

ドキュメントでさえ私に同意します：

値が配列の場合、jQuery は複数の値を同じキーでシリアル化します。つまり、{foo:["bar1", "bar2"]} は '&foo=bar1&foo=bar2' になります。

これは単に jQuery チームの不適切な判断によるものだと考えるのは正しいでしょうか?

List<Foo> getFoos ()リモートサーバーからデータを取得して返すメソッドがあります。

もちろん、ユーザーはサーバー上のデータと同期されていないデータを取得するため、リストのアイテム数を変更しないでください（アイテム数を変更したい場合は、のような特別なメソッドがありますaddFoo ()）。

最初のアプローチは、配列を返し、メソッドのシグネチャをに変更することでしたFoo[] getFoos ()。しかし、Javaでより一般的であり、ユーザーがコレクションを操作する方が便利なので、署名をに変更しましたList<Foo> getFoos ()。このメソッドは常に

Collections.unmodifiableList (originalList)

したがって、ユーザーがリストを変更しようとすると、RuntimeExceptionが発生します。

同様の場合のAPI設計に関する推奨事項はありますか？

私は、多数のリモート Web サービス ベースのリソースへの簡単なアクセスを提供する API に取り組んでいます。

これらのリモート リソースの一部では、対話の前に特別なパラメーターを渡す必要があります。たとえば、1 つは開発者のキーのペアを渡す必要があり、もう 1 つはキーのペアと一意の識別子を必要とします。3 番目のものは、これらのパラメーターをまったく必要としません。現在、3 つのサービスを使用していますが、その数を増やすことができます。

Web サービスごとに、対応する API の実装があります。問題は、未知の数の文字列を未知の意味で渡す可能性を API に導入する方法がわからないことです。

私の提案のいくつか：

1.

2.

ServiceParams はマーカー インターフェイスです。この場合、次のようなヘルパー クラスがあります。

長所: 各サービスの意味のあるパラメーター名。

短所: 4 番目のサービスをサポートする場合、ユーザーは factory モジュールを更新する必要があります。最初のケースでは、ユーザーは新しいモジュールをダウンロードするだけです。

3.

長所：最も使いやすい。ユーザーは追加の操作を行う必要はありません (ServiceParams のプロパティの作成など)。

短所：最も目立たない方法。ユーザーは、作成したいサービスに対応するパラメーターのセットを知っている必要があります。

4-6:

同じバリアントですが、params はファクトリ メソッドではなく Service インスタンス (たとえば、その init() メソッド) に渡されます。

長所: ユーザーは、同じサービスの新しいインスタンスを作成する必要がなくても、必要に応じてサービスのキーを変更できます。

短所：より複雑な方法で、利益が疑わしい.

どのバリアントが好きですか? なんで？あなたのバリエーションは大歓迎です。

JavaMail を使用する、私が書いていないコードを修正していて、JavaMail API がそのように設計されている理由を理解するのに少し苦労しています。理解できれば、もっといい仕事ができる気がします。

私たちは次のように呼びます：

では、Eclipse が次のように警告するのはなぜですか。

静的メソッドの呼び出しですか?

Transport オブジェクトを取得して、そのオブジェクトを使用してメッセージを送信できないのに、そのオブジェクトに固有の設定を提供するのはなぜですか? Transport クラスは、メッセージの送信に使用するサーバーやその他の設定をどのように認識しているのでしょうか? 信じられないほどうまく機能しています。2 つの異なるサーバーのトランスポート オブジェクトをインスタンス化した場合はどうなるでしょうか。どちらを使用するかをどのように知るのでしょうか?

この質問を書いている過程で、私は本当に呼び出す必要があることを発見しました:

では、静的な Transport.send() メソッドの目的は何でしょうか? これはデザインが悪いだけですか、それとも理由がありますか?

例えば：

そして、これはaCertPathValidatorが使用される場合にのみ使用されます。窮地に立たせるための2つの選択肢があります。

• 再びシングルトンですが、各プロパティにゲッターとセッターがあります
• 現在のコンテキストに関連するプロパティを含むオブジェクト:( CertPathValidator.setValidatorProperties(..)すでにセッターがありますPKIXParameters。これは良いスタートですが、すべてが含まれているわけではありません）

いくつかの理由が考えられます：

• コマンドラインからプロパティを設定する-コマンドラインから上記のクラスのデフォルト値への単純な変換は簡単です
• さまざまなプロバイダーによる追加のカスタムプロパティを許可します-それらは持つことができ、キャストすることpublic Map getProviderProperties()もできます。public Object ..

これらのプロパティは常に最も目に見える場所にあるとは限らないため、興味があります。APIの使用中に表示する代わりに、（運が良ければ）取得する前に数十のGoogle検索結果を確認する必要があります。なぜなら-そもそも-あなたは自分が何を探しているのかを常に正確に知っているとは限らないからです。

私が今観察したもう1つの致命的な欠点は、これがスレッドセーフではないことです。たとえば、2つのスレッドがocspを介して失効を確認する場合は、ocsp.responderURLプロパティを設定する必要があります。おそらく、互いの設定を上書きします。