PHP ベースの Web アプリケーション、データベース、CMS のデフォルト関数を API でラップする方法を探しています。
いろいろ調べてみたところ、いくつかの「スケルトン」フレームワークが見つかりました。私の質問の回答に加えて、トニック、非常に軽量なので気に入っている REST フレームワークです。
私は REST のシンプルさが一番好きで、それをベースに API アーキテクチャを作成したいと考えています。基本原理を理解しようとしていますが、まだ完全には理解できていません。そのため、いくつか質問があります。
1. 私の理解は正しいでしょうか?
たとえば、「ユーザー」というリソースがあるとします。次のようにいくつかの URI を設定できます。
/api/users when called with GET, lists users
/api/users when called with POST, creates user record
/api/users/1 when called with GET, shows user record
when called with PUT, updates user record
when called with DELETE, deletes user record
これは今のところ RESTful アーキテクチャの正しい表現でしょうか?
2. 動詞がもっと必要
理論上は、作成、更新、削除で十分かもしれませんが、実際にはさらに多くの動詞が必要になります。これらは更新リクエストに埋め込むことができるものであることは理解していますが、特定の戻りコードを持つことができる特定のアクションであり、これらすべてを 1 つのアクションにまとめることは望ましくありません。
ユーザーの例で思い浮かぶものは次のとおりです。
activate_login
deactivate_login
change_password
add_credit
RESTful URL アーキテクチャでこのようなアクションをどのように表現すればよいでしょうか?
私の直感では、次のようなURLにGET呼び出しを行うでしょう。
/api/users/1/activate_login
ステータス コードが返されることを期待します。
しかし、これは HTTP 動詞を使用するという考えからは外れています。どう思いますか?
3. エラーメッセージとコードを返す方法
REST の優れた点の大部分は、標準の HTTP メソッドの使用に由来しています。エラーが発生すると、3xx、4xx、または 5xx のエラー ステータス コードを含むヘッダーが出力されます。詳細なエラーの説明には、本文を使用できます (そうでしょうか?)。ここまでは順調です。しかし、何が問題だったのかをより詳細に説明する独自のエラー コード(例:「データベースへの接続に失敗しました」や「データベースへのログインが間違っています」) を送信するには、どうすればよいのでしょうか? メッセージとともに本文にエラー コードを挿入すると、後で解析する必要があります。このような場合の標準ヘッダーはありますか?
4. 認証方法
- REST 原則に従った API キーベースの認証はどのようなものになるでしょうか?
- REST クライアントを認証するときにセッションを使用することには、REST 原則の明白な違反という点以外に、欠点はありますか? :) (これは半分冗談ですが、セッション ベースの認証は既存のインフラストラクチャとうまく連携します。)
ベストアンサー1
私はこの質問に数日遅れて気づきましたが、少しは洞察を加えることができると思います。これがあなたの RESTful な取り組みに役立つことを願っています。
ポイント 1: 正しく理解していますか?
正しく理解しました。これがRESTfulアーキテクチャの正しい表現です。次のマトリックスは以下からご覧いただけます。ウィキペディア名詞や動詞を定義するのに非常に役立ちます:
次のようなコレクションURIを扱う場合:http://example.com/resources/
GET : コレクションのメンバーを一覧表示し、さらに移動するためのメンバー URI も指定します。たとえば、販売中のすべての車を一覧表示します。
PUT : 「コレクション全体を別のコレクションに置き換える」という意味として定義されます。
POST : コレクションによって ID が自動的に割り当てられるコレクションに新しいエントリを作成します。作成された ID は通常、この操作によって返されるデータの一部として含まれます。
DELETE : 「コレクション全体を削除する」という意味として定義されます。
次のようなメンバーURIを扱う場合:http://example.com/resources/7HOU57Y
GET : 適切な MIME タイプで表現されたコレクションのアドレス指定されたメンバーの表現を取得します。
PUT : コレクションの指定されたメンバーを更新するか、指定された ID で作成します。
POST : アドレス指定されたメンバーをそれ自体のコレクションとして扱い、その新しい従属メンバーを作成します。
DELETE : コレクションの指定されたメンバーを削除します。
ポイント2: 動詞がもっと必要
一般的に、動詞がもっと必要だと思ったら、実際にはリソースを再識別する必要があるかもしれません。REST では常にリソース、またはリソースのコレクションに対して操作を行っていることに注意してください。リソースとして何を選択するかは、API 定義にとって非常に重要です。
ログインの有効化/無効化: 新しいセッションを作成する場合は、「セッション」をリソースとして考慮する必要があります。新しいセッションを作成するには、http://example.com/sessions/本文に資格情報を含む POST を使用します。期限切れにするには、PUT または DELETE (セッション履歴を保持するかどうかによって異なります) を使用しますhttp://example.com/sessions/SESSION_ID。
パスワードの変更:今回のリソースは「ユーザー」です。本文に古いパスワードと新しいパスワードを指定した PUT が必要ですhttp://example.com/users/USER_ID。「ユーザー」リソースに対して操作を行っており、パスワードの変更は単なる更新要求です。これはリレーショナル データベースの UPDATE ステートメントと非常によく似ています。
私の直感では、次のようなURLにGET呼び出しを行うでしょう。
/api/users/1/activate_login
これは、REST の核となる原則である「HTTP 動詞の正しい使用」に反しています。GET リクエストは副作用を残さないはずです。
たとえば、GET リクエストでは、データベースにセッションを作成したり、新しいセッション ID を持つ Cookie を返したり、サーバーに残留物を残したりしてはなりません。GET 動詞は、データベース エンジンの SELECT ステートメントに似ています。静的 Web ページをリクエストする場合と同様に、同じパラメータでリクエストされた場合、GET 動詞を使用したリクエストに対する応答はキャッシュ可能である必要があることに注意してください。
ポイント3: エラーメッセージとコードを返す方法
4xx または 5xx HTTP ステータス コードをエラー カテゴリとして考えます。エラーの詳細は本文で説明できます。
データベースへの接続に失敗しました: /データベースへのログインが正しくありません: 一般に、これらのタイプのエラーには 500 エラーを使用する必要があります。これはサーバー側のエラーです。クライアントは何も間違っていません。500 エラーは通常、「再試行可能」と見なされます。つまり、クライアントはまったく同じリクエストを再試行でき、サーバーの問題が解決されると成功すると予想できます。本文に詳細を指定して、クライアントが人間に何らかのコンテキストを提供できるようにします。
他のカテゴリのエラーは 4xx ファミリーで、一般的にはクライアントが何か間違ったことをしたことを示します。特に、このカテゴリのエラーは通常、クライアントに対して、リクエストが永続的に失敗し続けるため、そのまま再試行する必要がないことを示します。つまり、クライアントはこのリクエストを再試行する前に何かを変更する必要があります。たとえば、「リソースが見つかりません」(HTTP 404) または「不正なリクエスト」(HTTP 400) エラーがこのカテゴリに分類されます。
ポイント4: 認証の方法
ポイント 1 で指摘したように、ユーザーを認証する代わりに、セッションの作成を検討することもできます。適切な HTTP ステータス コード (200: アクセスが許可されました、または 403: アクセスが拒否されました) とともに、新しい「セッション ID」が返されます。
次に、RESTful サーバーに「このセッション ID のリソースを GET できますか?」と問い合わせます。
認証モードはありません - REST はステートレスです。セッションを作成し、このセッション ID をパラメータとして使用してサーバーにリソースを提供するように要求し、ログアウト時にセッションをドロップまたは期限切れにします。