REST APIの設計規則を解説｜設計する際のポイントや必要なスキルもご紹介します

RESTとは「Representational State Transfer」の略でシンプルなWebシステムの設計のやり取りをします。

APIは「Application Programing Interface」のことでアプリケーションやソフトウェアを統合するためのツール・定義・プロトコルです。

代表的なものではグーグルマップがあげられます。グーグルが提供するサービスでAPIを公開しているため誰でもアクセスして情報が取得できます。

RESTはそのシンプルさとスピードからWeb上でデータを取得する際に最もよく利用されています。

REST APIは汎用性の高いアプリケーションやソフトウェア同士の通信をやり取りするAPIの一種です。

今回はクラウドサービスが進む中で注目されているREST APIの設計規則のほかポイントや必要なスキルを紹介します。

REST APIの特徴

 APIはデバイスとアプリケーションの相互通信の方法を定義するためのルールで、RESTと呼ばれる設計原則にのっとって策定されたものです。

RESTは適用範囲が広い抽象的なものであり、RESTの考え方をAPIに適用したものをRESTful APIといいます。

REST APIとRESTful APIはどちらもRESTの原則によって設計されたAPIであることからどちらも同じ意味で捉えられています。

下記の4つがRESTの原則です。

• アドレス可能性
• 統一インターフェース
• ステートレス性
• 接続性

アドレス可能性とはURI（Uniform Resource Identifier）を用いて情報が提供できることであり、全てのアドレスが一意的なURIを持ち、見ただけでなんの情報か理解できることです。

統一インターフェースは情報の取得・更新・削除といった操作がHTTPメソッドを使って表現できなければなりません。

ステートレス性はセッションなどの状態は管理せず、そのリクエストで完全に処理が完結できることが必要になります。

接続性はある情報に別の情報へのリンクを含めることで実際に接続ができることが求められます。

REST APIとSOAP APIの違い

REST APIとSOAP APIはいずれもHTTPプロトコルを活用する点は同じですが、SOAP APIの方が厳格なメッセージパターンを持つためより安全だといえます。

アーキテクチャスタイルのREST APIは柔軟性に優れ、軽量でもあるためモバイルアプリケーション開発などに最適です。

SOAP APIは多くの企業のニーズに合わせたセキュリティやトランザクション・コンプライアンスを提供します。

ただ、SOAP APIは負荷が大きいためREST APIに比べスピードは遅くなる傾向がありますが、Webセキュリティサポートサービスが充実していることから企業側のニーズが高いといえます。

REST APIを設計する際のポイント

REST APIを設計する際のポイントはシンプルであること・APIの利用者が何を必要としているか・どうやれば使いやすいかを念頭に設計する必要があります。 詳しくみていきましょう。

リソースの決定

REST APIを設計する前に操作するリソースを明確にして、それに必要となるAPIを洗い出さなければなりません。

特に下記の点についておさえておきましょう。

• APIユーザーが必要とする情報源
• リソースに必要な操作

APIユーザーはどのような情報が必要なのか、そのリソースに対してどのような操作が求められるのかを考えなければなりません。

リソースの操作はHTTPメソッドで表現します。例えば会員情報を読み込む時は「GET」、追加する時は「POST」といった具合です。

「PUT」はリソースの変更であり、「DELETE」はリソースの削除を意味します。詳しくはのちほど解説します。

リソースを決定する作業はデータベース設計に似ていますが、APIはインターフェースのためひとつのリソースの中にメタデータとして関連する情報を持つことができます。

URLの設計

リソースを洗い出したら次はURLの設計に入ります。 URLはさまざまな要素に関わるため慎重に設計しなければなりません。

URLが設計できたら今後WebAPIの拡張性を高められるように、仕様が理解しやすいものにしておくことが重要です。

URL設計で気をつけておくべき点は下記の通りです。

• ひと目でAPIと分かるURLにする
• URLにAPIのバージョンを含める
• URLには動詞を含めず複数形の名詞だけで構成する
• アプリケーションにファイルの拡張子は含めない
• リソースの関連性がひと目で分かること

誰が見てもAPIと分かることは非常に大切で、例としてはディレクトリに分ける方法とサブドメインに分ける方法があります。

URLにAPIバージョンを含めればREST APIを使用する開発者がAPIのバージョンを選択しやすく、切り分けもしやすくなります。

URLはリソースそのものを表し、操作についてはHTTPメソッドで表現することが必要です。 URLの末尾には言語に関連した拡張子を付けません。

それは将来的にAPIの仕様が変更された際に容易に変更作業がしやすくなるからです。 また、URLは実装が手間になるため長すぎないようにしてください。

URLは見ただけでリソースがどこのものか分かるようにしておくといちいち調べる手間が省けます。

HTTPメソッドを決定

HTTPメソッドはクライアントがサーバーにして欲しいことを依頼する時に、リクエストの種類に応じてHTTPメソッドの種類を切り替えることで利用できます。

一番よく利用されるメソッドは先ほど述べた4つがあり、Web開発する上で多く使われます。

APIの設計をする場合はこの4つのメソッドをしっかり理解しましょう。

「GET」はデータ取得をする時に利用するメソッドで、「POST」はクライアントからサーバーにデータを送信する時に使います。

「PUT」はPOST同様にクライアントからサーバーにデータを送る際に使いますが、主に既存データ更新で使われるのが一般的です。

「DELETE」は既存データを削除したい時に使います。

REST APIの設計の規則

REST APIの設計をする際はいくつかの規則があります。ここでは6つの規則についてみていきましょう。

統一インターフェース

インターフェースが統一されていればブラウザ・JavaScriptコード・モバイルアプリケーションなどRESTを利用するクライアントであれば同じ方法でサーバーが呼び出せ、リソースにアクセスが可能です。 Webサービスにおけるリクエストとレスポンスでは、クライアントはサーバーでリクエスト処理に必要な情報を送信します。

サーバーは要求されたリソースを変更・削除またはリソースにアクセスするための情報を含むレスポンスを返さなければなりません。

リソース表現にはリソースを削除または変更するための必要なデータが含まれているからです。

ステートレス

ステートレスはサーバーにクライアントに関するデータが含まれていないことを意味し、サーバーにユーザーの状態をメモリやデータベースに保存しておけます。

そのためにはサーバーがデータを返す情報が全てリクエストに含まれている必要があります。 ステートレスではアプリケーションの維持管理はユーザー側が行わなければなりません。

将来のリクエストに対応するためユーザーによる呼び出しに関するオーバーヘッドデータは保持する必要がなく、サーバーが軽量化されるメリットがあります。

ステートレスアーキテクチャでは拡張も容易です。

階層型システム

階層型システムとはユーザーとサーバーを完全に切り離すことで各アプリケーションがアクセスできる情報を制限することでコンポーネントの管理が強化されます。

コンポーネントの階層に分けて管理することで同じレベル内のほかのシステムとしか相互作用ができなくなります。

キャッシュ

キャッシュ機能とは頻繁に利用するデータなどを格納する機能で、RESTアーキテクチャスタイル内の情報はキャッシュ可能か不可能かをラベル付けしなければなりません。

キャッシュ機能を活用すればリソースの鮮度に基づいて、一度取得したリソースをクライアント側で使い回すことができます。

クライアント・サーバーアーキテクチャ

RESTはクライアント・サーバー、およびリソース（データ）で構成され、Request-ResponseはHTTPリクエストとレスポンスによって処理されます。

RESTではクライアントとサーバーは互いに完全に独立している必要があり、サーバーはクライアントアプリケーションを変更できないように設計しなければなりません。

その逆の場合、サーバーは要求されたリソースを提供するジョブのみを実行します。

コードオンデマンド

コードオンデマンドとはプログラムコードをサーバーからダウンロードし、クライアント側でそれを実行するアーキテクチャスタイルのことをいいます。

メリットはクライアント側が後から拡張できることであり、デメリットはネットワーク通信におけるプロトコルの可視性が低下することです。

REST APIの基本的なHTTPメソッド

HTTPではリソースに対して実行したいアクションを示すリクエストメソッドを定義しています。

それぞれのメソッドにはいろいろな意味があり、メソッドのグループで共有されています。 詳しくみていきましょう。

GET

「GET」は指定したリソースの表現をリクエストするものであり、使用されるリクエストはデータの取り込みに使われます。

POST

「POST」はクライアントがデータをサーバーに送信したい時に使います。GET同様にサーバーがクライアントに情報を返しても構いません。

HTMLの要素ではGETとPOSTでしか送信ができません。 なお、POSTはサーバー上の状態を変更したり、副作用が発生したりすることが特徴です。