コミュニティベースのWebサイト用のAPIを構築する前に、開発者は何を知っておく必要がありますか？
重いコーディングを開始する前に、コミュニティベースのWebサイト用のAPIを設計および実装する開発者は、何を知っておく必要がありますか？ Twitter API 、 Facebook API 、 Flickr API などのAPIがたくさんありますが、これらはすべて良い例です。しかし、どのように 独自のAPIを構築する ？
どのテクノロジーを使用しますか？ [〜＃〜] rest [〜＃〜] のようなインターフェースを使用して、さまざまなプラットフォーム/クライアント/ブラウザー/コマンドラインツール（-のような）からAPIにアクセスできるようにすることをお勧めします。 curl ）。私は正しいですか？キャッシュ、可用性、スケーラビリティ、セキュリティ、潜在的なDOS攻撃からの保護、検証など、Web開発のすべての原則を満たす必要があることを私は知っています。APIに関して最も重要なことのいくつかは、下位互換性とドキュメントです。私は何かが足りないのですか？
一方、ユーザーの観点（つまり、APIを使用する開発者）の観点から考えると、APIに何を求めますか？良いドキュメント？コードサンプルがたくさんありますか？
この質問は Joel Coehoorn の質問 "公開Webサイトを構築する前に開発者は何を知っておくべきですか？" に触発されました。
この質問はコミュニティウィキなので、コミュニティのAPIを構築するときに対処する必要のあるすべてのことを1か所にまとめるのに役立つことを願っていますベースのウェブサイト。
本当にREST api）を定義したい場合は、次のようにします。
HTTPおよびメディアタイプ以外のすべてのテクノロジーの問題を忘れてください。
クライアントがAPIと対話する主なユースケースを特定します
架空のHTTPサーバーに対してこれらの「ユースケース」を実行するクライアントコードを記述します。 クライアントが開始する必要がある情報は、ルートAPIURLへのGETリクエストからの応答のみです。クライアントは、HTTP content-typeヘッダーから応答のメディアタイプを識別し、応答を解析する必要があります。その応答には、クライアントがAPIに必要なすべての操作を実行できるようにする他のリソースへのリンクが含まれている必要があります。
REST apiを作成する場合、オブジェクトモデルやプロセスモデルを公開するよりも、マシンの「ユーザーインターフェイス」と考える方が簡単です。マシンがAPIをプログラムでナビゲートすることを想像してみてください。応答、リンクの追跡、応答の処理、次のリンクの追跡クライアントは、サーバーがリソースを編成する方法に関する知識に基づいてURLを作成しないでください。
これらのリンクをどのようにフォーマットして識別するかが重要です。 REST APIはメディアタイプの選択ですを定義する際に行う最も重要な決定] ==。そのリンク情報を表す標準的な方法を見つける必要があります（考えてください- Atom 、 microformats 、 atom link-relations 、 Html5 link Relations ）または、特別なニーズがあり、多くのクライアントに本当に広いリーチが必要な場合は、独自の media-types を作成できます。
それらのメディアタイプがどのように構成されているか、およびそれらに含まれる可能性のあるリンク/リンク関係を文書化します。メディアタイプに関する特定の情報は、クライアントにとって重要です。サーバーがContent-Type：application/xmlを返すようにすることは、クライアントが応答を解析する以外のことをしたい場合には役に立ちません。クライアントは、タイプapplication/xmlの応答に何が含まれているかを知ることができません。 XMLスキーマを使用してこれを定義できると信じている人もいますが、これにはいくつかの欠点があり、REST "自己記述的メッセージ"制約に違反します。
URLがどのように見えるかは、クライアントの操作方法とはまったく関係がないことに注意してください。これに対する唯一の例外は、メディアタイプがテンプレート化されたURIの使用を指定し、それらのテンプレートのパラメーターを定義する可能性があることです。 サーバーサイドフレームワークの選択に関しては、URLの構造が重要になります。サーバーはURL構造を制御し、クライアントは気にしないでください。ただし、サーバー側のフレームワークがクライアントがAPIと対話する方法を指示しないようにし、APIの変更が必要なフレームワークの選択には十分注意してください。 クライアント/サーバーの相互作用に関する唯一の制約はHTTPである必要があります。