問題タブ [api-design]

次のような構造の REST サーバーにいくつかのリソースがあります。

• /someResources/foo
• /someResources/bar
• /someResources/baz

ここで、someResourceは遠く離れた分散オブジェクトのサーバー表現です。

その「分散オブジェクト」の表現をネットワークで調べてサーバーのキャッシュを更新することにより、サーバーにその表現を「リフレッシュ」するように伝えたいのです。つまり、単純に新しい値を PUT することはできません。

これに対するクリーンなRESTの方法は何ですか?

a)/refreshes/新しい「更新リクエスト」に POST しますか?

b) PUT (白紙の文書)http://ip/someResourcesですか?

c) 他に何か?

(a) は、更新コマンドを識別して追跡するための ID を提供するので気に入っていますが、作成するリソースが多すぎるのではないかと心配しています。何かアドバイス？

API 設計では、次のようなことを行うのが一般的ですか。

get の本体で、これはコレクションを埋めるプライベート メソッドを呼び出します。そのため、一貫性のあるオブジェクトを 1 つだけクライアントに公開します。私を混乱させるのは、クラスとそのメンバーを静的にすることが正しいかどうかです。結局のところ、オブジェクトを返すので、クラスも不変です (不変クラスは静的であるべきだと私は考え続けています)。static がステートレスをほのめかしていないことは承知しています。静的は、1 つのエンティティとして集中化されるもの (会社の詳細など) に適していると考えるのは正しいですか?

ありがとう

にない方法が1つあります：Lookup<,>ILookup<,>

のインスタンスを常に返すように見えるにもかかわらず、の戻り型がEnumerable.ToLookup<>()宣言されているのはなぜですか？代わりに戻り型がであると宣言された場合、上記のメソッドはキャストなしで使用できます。ILookup<,>Lookup<,>Lookup<,>

私はこのレクチャー ( http://www.youtube.com/watch?v=aAb7hSCtvGw&hl=nl ) を視聴しており、約 34 分で、スライドの箇条書きに「文書の状態空間を非常に慎重に」と記載されています。

状態空間とは なぜ「非常に注意深く」文書化する必要があるのでしょうか? 残念ながら、私が現在投稿しているマシンには音声がありませんが、スライド自体は私の学習に非常に役立ちます (音声があればさらに役立つでしょう)。

ありがとう

私が書いているシステムの内部 API を設計しています。API 設計で考慮すべきベスト プラクティスは何ですか?

スクリプトインクルードを使用したGoogleマップのAPIの使用方法は気に入っていますが、心配しています。

私のAPIは「セミプライベート」です。つまり、インターネット経由でアクセスできますが、データの安全な送信とある種の認証が可能になるはずです。データはネットワーク上で非公開のままにする必要があり、ある消費者が別の消費者のデータを取得できないようにする必要があります。

SSLとある種の認証を使用してデータを安全に保ちながら、サーバー側のプロキシを必要としないプレーンなHTMLページから「水平方向に」アクセスするにはどうすればよいですか。キーを管理する必要がありますか？キーは傍受されることなくサーバーにどのように投稿されますか？OpenId（または他のサードパーティ認証）を使用してAPIユーザーを認証できますか、それとも独自の認証メカニズムを作成する必要がありますか？私はグーグルのいたるところにいて、APIを安全に設計してデプロイするための良いガイドを見つけることができません。

現在、RESTとAJAXを使用してそれらを使用していますが、クロスドメイン呼び出しは不可能です。どんな助けや正しい方向へのポインタも大歓迎です。

C＃で永続的なコレクション（リストなど）を作成することを考えていますが、優れたAPIを見つけることができません。

Clojureの意味で「 persistent」を使用します。永続リストは、参照セマンティクスではなく値セマンティクスを持っているかのように動作するリストですが、大きな値型をコピーするオーバーヘッドは発生しません。永続コレクションは、コピーオンライトを使用して内部構造を共有します。擬似コード：

Clojureはそのようなデータ構造を使用しますが、さらにClojureではすべてのデータ構造が不変です。すべてのコピーオンライト処理を実行するにはオーバーヘッドが発生するため、Clojureは、データ構造を他のユーザーと共有していないことが確実な場合に使用できる一時的なデータ構造の形式で回避策を提供します。データ構造への唯一の参照がある場合は、すべてのコピーオンライトオーバーヘッドを実行するのではなく、直接変更してみませんか。

この効率を上げる1つの方法は、データ構造の参照カウントを維持することです（ただし、Clojureがそのように機能するとは思いません）。refcountが1の場合、唯一の参照を保持しているため、更新を破壊的に行います。refcountが高い場合は、他の誰かが値型のように動作するはずの参照を保持しているため、他のリファラーの邪魔にならないようにコピーオンライトを実行してください。

このようなデータ構造に対するAPIでは、refcountingを公開して、APIの使用性を大幅に低下させたり、refcountingを実行できなかったりして、すべての操作がCOWされた場合、またはAPIで不要なコピーオンライトのオーバーヘッドが発生する可能性があります。値型の動作が失われ、ユーザーはCOWを手動で実行するタイミングを管理する必要があります。

C＃に構造体のコピーコンストラクターがある場合、これは可能です。実際のデータ構造への参照を含む構造体を定義し、その構造体のコピーコンストラクタとデストラクタですべてのincref（）/ decref（）呼び出しを実行できます。

APIユーザーを煩わせることなく、C＃で参照カウントや構造体コピーコンストラクターのようなことを自動的に行う方法はありますか？

編集：

• 明確にするために、私はAPIについて質問しています。Clojureには、Javaで記述されたこれの実装がすでにあります。
• すべての操作でCOWされる実際のコレクションを参照する構造体を使用することにより、このようなインターフェイスを作成することは確かに可能です。refcountingの使用は、不要なCOWを回避するための最適化ですが、正常なAPIでは明らかに不可能です。

JAX-RS と JAX-WS は、API の作成に最適です。ただし、下位互換性の問題にはまったく対処していません。

API に新しい機能が導入されたときに古いクライアントが壊れないようにするには、基本的に、以前とまったく同じ入力および出力形式を受け入れて提供する必要があります。XML パーサーや JSON パーサーの多くは、何にもマップされていないフィールドや間違った型のフィールドを見つけた場合に適しているようです。

Jackson や Gson などの一部の JSON ライブラリは、ランタイム設定に基づいて、特定のオブジェクトに対して異なる入出力表現を指定できる機能を提供します。これは、多くの場合にバージョン管理を処理する適切な方法のようです。これにより、追加および削除されたフィールドに注釈を付けることで下位互換性を提供できるため、クライアントが使用している API のバージョンに従ってのみ表示されます。

私がこれまでに見つけた JAXB も他の XML データバインディング ライブラリも、この概念を適切にサポートしていません。それを JAXB-RI または EclipseLink Moxy に追加することは潜在的に可能に思えますが、困難です。

バージョン管理のもう 1 つの方法は、変更されたすべてのクラスをバージョン管理することです。多くの場合、API が公開されるたびに新しいパッケージを作成し、変更されたすべての DTO、サービス、およびリソース クラスを新しいパッケージにコピーして、タイプ情報は、バインディングおよびディスパッチ システム用にバージョン管理されます。このアプローチは、私にはもっと面倒に思えます。

私の質問は、下位互換性のために Java API プロバイダーをどのように設計したのですか? 何が機能し、何が機能しなかったか?

この件に関するケーススタディまたはブログ投稿へのリンクは大歓迎です。私はいくつかのグーグルを行いましたが、これについての議論はあまり見つかりませんでした。

Mercurial のコマンド ライン クライアントをラップするクラス ライブラリがあります。

私の意図は、すべての組み込みコマンドのサポートを実装することですが、それらに加えて、そこにはたくさんの拡張機能があります.

したがって、他の人も私も拡張機能のサポートを追加できるという意味で、ライブラリを拡張可能にする必要があります。より一般的で典型的な拡張機能 (少なくとも Mercurial にバンドルされている拡張機能のかなりの数) のサポートを追加する予定ですが、それでも外部から拡張できるようにしたいと考えています。

現時点では、コマンドの構文は次のようになります。

ただし、これは、プログラマーが拡張機能が単に追加された部分であると感じない限り、拡張機能にはあまり適していません。

たとえば、手動でこれを行うことができるように、追加のコマンド ライン引数のパブリック コレクションを公開するとします。

オブジェクト初期化子の一部として設定できるように追加の拡張機能を追加する簡単な方法はないようです。

私は流暢なインターフェイス構文に追加するか、おそらく切り替えることを考えていました。この場合、次のように書くことができます。

しかし、人々は流暢なインターフェースが好きではなく、おしゃべりになりすぎると感じています。

他にどのようなオプションがありますか?

私が欲しいもの、基本的に：

• 1 つの一般的な構文スタイル
  • 組み込みのものの両方について
  • 私のライブラリのユーザーによって追加された拡張機能と同様に

私のライブラリのユーザーは、新しいクラスと拡張メソッドを追加して Intellisense サポートを取得することでライブラリを拡張すると思いますが、オブジェクト初期化子で拡張メソッドを使用することはできません。それは私が望むものではありません。

どんなアイデアでも大歓迎です。

私は C# で API を設計しています。必要な関数の 1 つは、次のようなものです。

ChildType は次のように定義されます。

これは自明ですが、本質的には、問題のオブジェクトの子を作成し、子に含まれる値の型は、列挙型の値に基づいて文字列または double になります。

列挙型は公開されChildTypeているため、API のユーザーがアクセスできると思います。

私の懸念は、一部の言語が署名の列挙型を理解せず、この API にプログラムできないことです。これは心配すべきことですか、それとも私の恐れは根拠がありませんか?