問題タブ [api-design]

私の現在の雇用主は、サードパーティがホストする CRM プロバイダーを使用しており、2 つのシステム間にかなり洗練された統合層があります。CRM プロバイダーの機能の 1 つは、開発者が Java のような言語でビジネス ロジックを作成し、ユーザーがボタンをクリックしたり、新しいアカウントをシステムに送信したりするなどのイベントで、検証やビジネス ロジックを起動させることです。

私たちが利用する機能の 1 つは、ホストされたプロバイダーで実行されているビジネス コードが、ホストしている Web サービスを呼び出すことです。標準的な例として、営業担当者が新しい見込み顧客を入力し、ボタンを押してシステムに ping を送信し、電子メール アドレス、会社/名/姓などに基づいてその新しい見込み顧客を識別できるかどうかを確認し、識別できる場合は戻ってきます。その個人を表す内部 GUID。これはすべて問題なく機能しますが、正常な開発環境をセットアップして動作させるために何度も壁にぶつかりました.

したがって、私たちのユースケースは少し微妙ですが、これは一般に、サードパーティが使用する API を構築するすべての開発会社に適用でき ます。世界？

私たちのオフィスでは、すべての開発者がファイアウォールの内側にいるため、進行中のコードが外の世界 (私たちの場合は CRM プロバイダー) からアクセスされることはありません。ファイアウォールに穴を開けることはできますが、セキュリティ面の観点からは理想的とは言えません。特に、DMZ のようなエリアにいる必要がある開発者の数が多い場合。現在、DMZ で単一の開発マシンを試し、開発作業を行うために必要に応じてそこにリモート接続していますが、複数の開発者がボックスを必要とする場合、ましてや競合する可能性のある変更 (たとえば、異なるブランチ）。

これらのサービス用に偽のクライアントを構築することで、着信リクエストを単に偽装/偽装することを検討しましたが、これは機能セットを構築する上でかなり大きなオーバーヘッドです (ただし、本質的に API のテスト可能性を強化します)。これはまた、偽のリクエストペイロードではなく、実際のクライアント自体から発生する問題を診断/デバッグする必要がある場合があるという事実を回避するものではありません。

これらのタイプのシナリオで他の人は何をしましたか? マッシュアップのこの時代には、API を開発した経験のある人がたくさんいるに違いありません。

Webアプリ用のAPIを作成し、人々がグッドプラクティスとして提案できるものに興味があります。

私はすでにそれをバージョン管理することを計画しています（バージョン1はシステムの特定の側面のみを制御でき、バージョン2はそれ以上を制御できますが、これにはバージョン1と互換性のない認証の実行方法の変更が必要になる場合があります）。認証は、ユーザーがログインに使用する標準のユーザー名/パスワードとは異なります（誰かが悪意のあるツールを使用した場合、APIで許可されているものは何でも、完全ななりすましを行うことはできません）。

誰かがさらなるアイデア、またはあなたが使用した特に優れたAPIを備えたサイトの例を持っていますか？

私は何年にもわたって、次の問題パターンに頻繁に遭遇しました。

• 私は、スタンドアロン アプリケーションと、人々が他のアプリ内から使用できるコアのライブラリ バージョンで構成されるパッケージの複雑なコードを書いています。

• 私たち自身のアプリと、おそらくユーザーがコア ライブラリを使用して作成したアプリの両方が、バッチ モード (オフライン、スクリプト、リモート、および/またはコマンド ラインから) と対話型の両方で実行される可能性があります。

• ライブラリ/アプリは複雑で大量のランタイム入力を受け取り、重大なエラー メッセージ、入力構文の警告、ステータス メッセージ、実行統計など、さまざまなエラーのような出力が発生する可能性があります。これらはすべて付随的な出力であり、別の方法で別の場所に表示または保存されるアプリケーションの主な目的ではないことに注意してください。

• これらのいくつか (おそらく非常に深刻なもののみ) は、対話的に実行する場合、ダイアログ ボックスが必要になる場合があります。ただし、バッチ モードで実行する場合は、ユーザー入力を停止せずにログに記録する必要があります。また、ライブラリとして実行する場合、クライアント プログラムは明らかに、発生したエラーをインターセプトおよび/または調査する必要があります。

• Linux、Windows、OSX など、すべてクロスプラットフォームである必要があります。また、どのプラットフォームでもソリューションが奇妙にならないようにしたいと考えています。たとえば、stderr への出力は Linux では問題ありませんが、Windows では GUI アプリにリンクすると機能しません。

• ライブラリのクライアント プログラムはメイン クラスの複数のインスタンスを作成する場合があり、クライアント アプリが各インスタンスで個別のエラー ストリームを区別できると便利です。

• ライブラリ メソッドが単純な呼び出し (エラー コードや重大度、エラー メッセージを出力する printf のような引数) でエラーをログに記録するだけで十分であることに誰もが同意すると仮定します。論争の的となる部分は、これがクライアント アプリによってどのように記録または取得されるかです。

私はこれを何年にもわたって何度も行ってきましたが、解決策に完全に満足することはありません. さらに、実際にはユーザーにとってそれほど重要ではない種類のサブ問題です (ユーザーは何か問題が発生した場合にエラー ログを見たいと思っていますが、それを実装するための私たちの手法についてはあまり気にしていません) が、トピックはプログラマーを興奮させます。そして、彼らは常にこの詳細に途方もない時間を浪費し、完全に満足することは決してありません.

この機能を C++ API に統合する方法について知恵を持っている人はいますか、または受け入れられたパラダイムまたは優れたオープン ソース ソリューション (GPL ではありません。商用のクローズド アプリや OSS で使用できるソリューションが必要です) はありますか?プロジェクト）？

デメテルの法則に関するウィキペディアの記事には、次のように書かれています。

法則は「一点だけ使う」と簡単に言えます。

ただし、流暢なインターフェースの簡単な例は次のようになります。

それで、これは合っていますか？

外部からアクセスできる情報を含む Web サイトがあるとします。これらの情報は、尊敬されるクライアントによってのみ変更される必要があります。例: Google アナリティクスまたは WordPress API キー。(プログラミング言語に関係なく)そのように機能するシステムを作成するにはどうすればよいですか?

API を持っていて、非常に国際的なユーザーを持つ英国を拠点とする開発者である場合、API は

また

（簡単な例として 1 つの単語を取り上げます。）

英国を拠点とするエンジニアは、自分の「正しい」つづりについて非常に防御的であることがよくありますが、国際市場では米国のつづりがより「標準的」であると主張することができます.

問題はそれが問題だと思いますか？他のロケールの開発者は、GB のスペルに苦労していますか? それとも、通常、その意味は明らかですか?

すべて米国英語にする必要がありますか?

Netflix API の .NET ラッパー API を作成しています。

この時点で、URL を文字列または URI オブジェクトとして表すことを選択できます。私にはどちらにも良いケースがあるようです。

では、API を使用しているとしたら、どちらを優先しますか?

今日の Web サイトの API には 2 つのカテゴリがあるようです。

1. Facebook、Myspace などのように、サイトの機能を拡張できるようにする API。これらの API は非常に多様なようです。

2. Twitter、Flickr などの既存のサイト機能との対話を可能にする API。これらはすべて REST ベースであると主張していますが、実際には単に「HTTP 経由のデータ」です。

機能の拡張と外部とのやり取りの両方を可能にする Web サイトを作成する場合、参照モデルとしてどの既存の API を使用しますか?

バックグラウンド：

私は大学で「ソフトウェアの制約」という授業を受けています。最初の講義では、優れた API を構築する方法を学びました。

非常に悪い API 関数の良い例はpublic static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds);、C# のソケットです。この関数は、ソケットの 3 つのリストを受け取り、それらを破棄するため、ユーザーはソケットを に供給する前にすべてのソケットのクローンを作成する必要がありますSelect()。サーバーがソケットを待機できる最大時間を設定する int のタイムアウト (マイクロ秒単位) もあります。この制限は +/-35 分です (int であるため)。

質問:

1. API を「悪い」と定義するにはどうすればよいですか?
2. API を「良い」と定義するにはどうすればよいですか?

考慮すべき点:

• 覚えにくい関数名。
• わかりにくい関数パラメータ。
• 悪いドキュメンテーション。
• すべてが相互に関連しているため、1 行のコードを変更する必要がある場合、実際には他の場所で数百行を変更する必要があります。
• 引数を破棄する関数。
• 「隠れた」複雑さによるスケーラビリティの悪さ。
• ユーザー/開発者は、API を使用できるように、API の周りにラッパーを構築する必要があります。

内部 ORM ツールの一部を再設計しており、Field (CustomerFirstName などのデータベース内のフィールドを表すクラス) を最終開発者に直接公開したいと考えています。

これは簡単に実現できましたが、この Field クラスは以前は内部で使用されていてオープンすぎたため、API は少し見苦しくなってしまいました。たとえば、これは小さな例の 1 つにすぎません。IsDirty プロパティは読み取り専用ではありませんでした。これは最終開発者が改ざんできないものです。

IPublicField と IPrivateField の 2 つのインターフェイスを作成し、両方を実装するフィールド クラスを取得しようと考えました。ただし、 IsDirty の例を続けると、次のようなものは必要ありません。

...少し醜いだけでなく、Field クラスにキャストバックして、非読み取り専用メソッドに入ることができます。また、別のセッター メソッドを導入したくありませんでした。これは、考えたくない別の重大な変更になるためです。また、API の他の部分との不整合も生じるためです。

Field クラスの名前を InnerField に変更し、その周りにファサード/ラッパー スタイルの構造を次のように作成しました。

これはかなりうまくいっているようです。内部的には、InnerField は適切にオープンであり、最終開発者に影響を与えることなく、将来さらにオープンにする自由があります。外部的には、Field クラスは、最終開発者が必要とする単純化されたロックダウンされたツールを提供します。

それで、それが首尾一貫していると仮定して、あなたがこの状況でどのように進んだか、そして私の解決策が外部から合理的に見えるかどうか疑問に思っていました.

ありがとう！