プロジェクトのRESTful APIの重要な側面

この記事は私の頭の中で長い間醸造されてきましたが、まったく異なる形式です。

WEBサービス（ http://habrahabr.ru/blogs/development/108973/など ）のトピックに関する最後のいくつかの厄介な記事を読み、それらでRESTテクノロジーを使用したので、怠を捨て、時間を割り当て、「 「私の頭の記事で再フォーマット。

それで、簡潔に、あなたが記事で見つけるものとそれが誰に役立つか：



-プロジェクトのWEBサービスを作成することに興味がある、または計画している初心者向け

- プロが自分で何か新しいものを見つける可能性は低い

-一般的なRESTイデオロギー

-WEBサービスでのCRUDの適用

-ルーターを構築するためのKISSの原則

-ベストプラクティス

-少しPR;）

-参考文献、文献



判断を始める場所として、まず記事を読んでから、もう少しグーグルでお茶、コーヒー、下線を用意し、棚に思いを入れて、ちょっとおしっこを作り始めることをお勧めします。

一般的なアイデア

REST *（1）とは何ですか？

RESTは「Representational State Transfer」、つまり、クライアントにとって便利な形式でのデータの提示です。クライアントとは、クライアント<->サーバーモデルのクライアントソフトウェアを意味します。

また、HTTPプロトコルとRESTの原則を使用して作成されたWebサービスは、RESTful Webサービスと呼ばれます。

未経験者には、すぐに質問があるかもしれません。なぜそのようなサービスが必要なのでしょうか？ RESTおよびOAuthテクノロジーに基づく簡単な例を挙げましょう。GmailアカウントとDropboxアカウントを持っています。 Dropboxは招待された友人ごとに余分なスペースを提供しますが、手紙を手動で書いてGmailアドレス帳のすべてのアドレスをソートするのは退屈なだけでなく、長いことです。 Dropboxには、「来て、仲間、連絡先を自分でインポートして、招待状を送信する」という機能があります。 メールボックスからドロップボックスにパスワードを渡したくないという人はいないことは明らかです。 これは、RESTful Webサービスの「魔法」が作用する場所です。 APIを使用して（多くの人が言っているように、「api」ではなく）、dropboxはGoogle Webサービスにリクエストを送信し、Google認証ページに「送信」するため、Googleフォームにパスワードを入力します、Googleはユーザーを認証し、認証プロセス（認証）の成功についてDropboxに通知（access_tokenを提供）します。 最終的に、一意のトークン（access_token）を持ち、それをAPIの各リクエストに添付することで、Dropboxはパスワードについて何も知らなくても個人データを操作できます。

アーキテクチャはもともと正確にHTTPを使用して開発されましたが、RESTは必ずしもHTTPプロトコルの使用ではないことを覚えておくことが重要です。 RESTは、データの転送に任意のアプリケーション層プロトコルを使用できます。

CRUD

RESTful Webサービスを開発する場合、CRUD *方法論（2）を覚えておくことが重要です。これは、解読された翻訳では、create-read-modify-delete（create-read-update-delete）を意味します。

Webサービスの開発はHTTPプロトコルを使用して実行されるため、そのバンを使用する必要があります。つまり、プロトコルメソッドを使用して、リソースに対するアクションを決定します。 RESTの世界では、一般的に次の標準が受け入れられています。

POST-作成

GET-読み取り（読み取り、受信）

PUT-更新（変更、更新、または作成。存在しない場合は、このバージョンでも使用されることがあります）

DELETE-削除（削除）

PUTとDELETEはメソッドの実装が困難であり、ブラウザの機能により、これらのメソッドはクライアントブラウザー側でAJAXを使用して「人間的に」実装できることに注意する必要があります。さらに、すべてのブラウザーで動作することは不可能と思われます。 したがって、POSTメソッドの「オーバーロード」を通じてこれらのメソッドを使用するのが慣例です。 言い換えれば、POSTメソッドを使用して、オーバーロードするメソッドの名前を含む、ある種の予約済み変数（http_methodなど）を送信しています。 POST + http_method = put-サーバー側に、クライアントがリソースを介してPUTを要求したことを明確にします。

ルーターを構築するときのキスの原則

そもそも、KISSを解読します-まだ理解していない人のために、小さくてシンプルに保つ-シンプルで小さなものに固執し、言い換えれば、誰もがアクセス可能で理解しやすく、覚えやすいようにします。

Webサーバーからデータを受信するには、クライアントは連絡する必要があるURLを知る必要があります。 これらの同じユニバーサルリソースポインターを「構築」する原則について説明します。

まず、サービスに合った基本的なルールセットを決定します。 たとえば、当社のoDesk社では、ベースが/ apiであるURIはRESTful APIリソースであることを示しました。 必要に応じて、別のサブドメインに配置できます。ここでは、1つのドメインの「内部」のクエリであっても、クロスブラウザクエリやその他の落とし穴を覚えておく価値があります。

次のポイントは、リソースルーター（データにアクセスできるアドレス）を作成することです。 住所を編集する際に適切な方法と見なされるいくつかの点に注意してください。

-慣用的なグループへの分類：mc-メッセージセンターリソース、チーム-コマンドリソースなど

例：/ api / mc / ...

-バージョン管理

例：/ api / mc / v1 / ...

-アクセスが許可されるリソースの明確な名前

例：/ api / mc / v1 / prefs / ...-メッセージセンターの設定へのアクセス

-URLの下に永続データを入力する

例：/ api / mc / v1 / prefs / mydevelopersuid

-応答形式の定義：ルーターURLの名前、または「システム」変数のいずれか

例：/api/mc/v1/prefs/mydevelopersuid.json-oDeskは、JSON形式の応答、XML形式の.xmlなどが必要な場合に接尾辞「.json」を使用します。 / mc / v1 / prefs / mydevelopersuid？tqx = out：json-これはGoogleがGDSで行うことです。 / api / json / mc / v1 / prefs / mydevelopersuidは別の可能なオプションであり、形式はルーターの一部です。

ベストプラクティス

ここで多くのことを話すことができ、長い間、私は主なポイントをリストします：

-常にjson形式で応答を受信する機能を提供します。 そのため、AJAXアプリケーションの世界では、JSON *（3）がクライアント部分とサーバー部分の間でデータを転送するための事実上の「標準」になっています。

-承認のために検証済みの実績のあるスキームを使用する

md5データ署名などを使用してスクーターを再発明しないでください。データ保護の専門家を信頼してください。 OAuthはさまざまな言語のライブラリでいっぱいであるため、あなたのために発明されました-この力を使用してください。 OAuthが必要ない場合は、Flickrで実装されているAPIKeysを試してください。 いくつかのオプションがあります-OpenIDとその他、私は皆を考慮しません-私は本質を知らせました。

-httpsが必要な場所を忘れないでください

証明書がIPのドキュメントに自己記述されている場合は、それを必ず記載することを忘れないでください。 近隣のワークショップの同僚の時間を高く評価し、証明書の有効性のチェックがあるからといって、アプリケーションのバグを探しないようにします。

-答えに不明瞭なものを決して「投げ出さない」：Webサーバーのエラー、致命的、データベースとの接続の問題など。 これらはすべて、RESTful Webサーバーによって処理され、要求された形式で明確な回答を提供する必要があります。 つまり、クライアントへの応答時に明確なエラーを提供します。 応答形式とヘッダーは別のトピックです。 RFC 2616 *（4）に従って正しいHTTPステータスを返すことをお勧めします。ステータスによりメッセージ本文を送信できる場合は、本文に短いメッセージがあります。 一部の人々は、常に本文にステータス「200 OK」を与えることを好むため、クライアントは常にメッセージを解析し、本文にエラーメッセージ/タグが存在するかどうかを確認する必要があります。 明確な慣行や一般的な意見はまだありません！

-APIにドキュメントを書く。そうでなければ、ちょっと、おしっこ、それは役に立たない:)

-そして最後に、最初にRESTful Webサービスの内部アーキテクチャを考え直します。ロジックは要求された形式と同じである必要があり、データ変換は各形式ごとに個別に実行する必要があります。 これにより、ルーターを簡単かつ迅速に拡張し、必要に応じて、データを表示するための新しい標準を追加できます。

PR

oDeskのRESTful APIのメイン開発者であり（API-developers.odesk.comはPRで、健康のために使用してください！:)）、RESTサービスを長い間行っているので、この分野の基本的な知識を共有することが適切だったと思います。 私を信じるか信じないかはあなたの個人的な権利ですが、それでも私は、少なくとも少し読んでも自分自身のために利益を見つけて、少なくともあなたの知識をリフレッシュしてくれることを願っています;）



RESTアーキテクチャにはまだ多くの疑問が残されており、多くの場合ホリバーにつながります。私の意見があなたの意見と一致しない場合でも私を責めないでください。



PSこの記事は基本的な側面のみを扱っており、 Webサービスを作成するための詳細な指示、本などを提供することを意図していません。

リンク*

（1） http://en.wikipedia.org/wiki/Representational_State_Transfer

（2） http://en.wikipedia.org/wiki/Create,_read,_update_and_delete

（3） http://en.wikipedia.org/wiki/JSON

（4） http://www.w3.org/Protocols/rfc2616/rfc2616.html

参照：RESTful Web Services（Leonard Richardson、Sam Ruby）、O'Reilly Media、Inc.

Yahoo RESTグループ： http : //tech.groups.yahoo.com/group/rest-discuss/