REST APIの始め方
Aug 25, 2017 · 6 min read
ここでは、広く使われるREST APIの概要を、下の記事を参考にまとめていきます。効率的なAPIの作り方は何かを、何回かの記事に分けて、学習していきます。
まずは、REST APIに備わる、6つのルール(制約)について見てきます。
- Uniform Interface
→
①client側とserver側のinterface(仲介機能)を定義します。
②まず、ソースは特定のリクエストに対して識別されます。つまり、ソースはリクエストに応じたソースを表すデータを返します。
③clientがソースの情報を持っている時、そのデータが必要十分なデータをであれば、server側のソースを改変できます。
④また、どのように処理を行うかを、メッセージは正しく記述します。
⑤サーバーが返すデータには、必要なデータ(body contentd, response codes, response headers)に加えて、オブジェクトを取り出すのに不可欠なURL(リンク)を含ませる必要があります。 - Stateless
→
リクエストをサーバー側が正しく認識するために(ソースを識別するため)、クライントは全ての情報を送る必要があります。
これによって、全てのクライアントが使えるAPIを構築でき、サーバー側はApplicationのStateに処理を行う必要がなくなります。つまり、一度完全なリクエストを受け取れば、何度もリクエストを、サーバーは要求する必要がなくなります。 - Cacheable
→
キャッシュの制御を行うことは、クライアントに過多なリクエストを送る必要性を減らします。 - Client-Server
→
REST APIがclientとserver側の中間にあることで、それぞれがお互いの機能を気にすることなく、より効率的な開発が可能になります。 - Layered System
→
クライアントとサーバーの間に中間レイヤーを設けることで、機能の拡張性と、セキュリティの向上させることができます。 - Code on Demand
→
上の制約を踏まえて、その利便性を壊すことがない状況においては、serverはclientの、clientはserverの機能を付けていくことも可能になります。
API設計において(それがRESTで無かったとしても)、次のルールを守ることは、機能的なAPIに必要なものとなります。
- Use HTTP Vervs to mean something
→
HTTPリクエストを送る際は、(GET, POST, PUT, DELETE)などを使って、何の処理が行われているかを、それ自体が表すものを使います。またGETリクエストでソースを変更するような処理は、行うことは駄目です。 - Sensible Resource Names
→
ソースやパスの名前は、それ自体が意味を表せるような明確な意味を持たせます。ソースの名前は名詞を使い、そのURI(パス)から、構造が見やすくなるように名前が付けられます。HTTPメソッドはリクエスト内に含まれます。 - XML and JSON
→
default設定としては、JSONタイプを扱うことが好まれます。理想としては、コストの中で、XMLとの併用があります。
基本はJSONです。更には、AJAX形式のinterfaceをサポートすることが、望ましいです(JSONでは .wjsonと言われ、JSONをラップしたものになります) - Create Fine-Grained Resources
→
小さくて簡単に定義されたソースから始め、それらにCRUD機能を提供します。
個々のソースから、大きなリソースを作成する方が簡単なアプローチになります。 - Consider Connectedness
→
レスポンス内に、API自身を示すリンクは、必ず含まれる必要があります。
Locationヘッダーを使用して、POST経由で、ソースを作成するリンクを格納します。 ページネーションをサポートするレスポンスで返されたコレクションには、 ‘first’、 ‘last’、 ‘next’、 ‘prev’のリンクが使われます。
また、REST APIでは、次の用語がよく使われるものになりますので、その定義を確認していきます。
- Idempotence(べきとうせい)
→
RESTfulなサービスでは、操作(サービス呼び出し)をIdempotence、冪等性(べきとうせい)と定義します。
クライアントは同じ呼び出しを、同じ結果を生成しながら、繰り返し行うことができます。つまり、複数の同一の要求を行うことは、単一の要求を行うことと同じ効果をもたらします。 冪等(ぺきとう)の操作では、サーバー上で同じ結果が発生しますが、応答自体は同じではない可能性があります(たとえば、リクエスト間で、ソースの状態が変わる可能性があります)。PUT, DELETEがこれに該当します。 - Safety(安全性)
→
安全性とは、あるメソッドを呼び出すことが、副作用を引き起こさないことを意味します。したがって、クライアントはサーバー上の副作用を心配することなく、繰り返し安全な要求を行うことができます。これは、サービスがGET、HEAD、OPTIONS、およびTRACE操作の安全定義に準拠している必要があることを意味します。そうしないと、クライアント側を混乱させるだけでなく、Webキャッシング、検索エンジン、その他の自動化されたエージェントに問題が発生し、意図しない変更がサーバー上で発生する可能性があります。
定義上は、安全な操作はサーバ上で同じ結果を生成するため、冪等(べきとう)であるといえます。
安全なメソッドは、読み取り専用操作として実装されます。ただし、安全性とは、サーバーが毎回同じ応答を返さなければならないという意味ではありません。先程にも出てきた、PUT、DELETEはソースの状態を変えるので、応答はリクエスト毎に変化します。
以上が、REST APIを開発に必要な、用語の定義になります。
次回は、HTTPリスエストで使われる処理の名前の定義を、確認していきます。
