概要
こんにちは。プラットフォーム開発部でリードエンジニアをしているchanceです。
私たちのチームでは現在、開発部内向けの API 設計ガイドラインを整備しようとしています。
API 設計において、REST は基本中の基本です。ガイドラインとしてまとめるからには適当なことは書けませんので、改めて REST の原則から確認しました。新しい技術を追いかけるのはもちろん重要ですが、こういった基本の技術をしっかりと理解することも同じように重要です。
この記事では、調べた内容のシェアとして、REST の誕生から原則、リソース指向アーキテクチャの概要や特性などを解説します。文字文字しくなってしまいましたが、ご容赦ください。
REST の誕生
REST は、Web システムを構築するための設計思想として、Roy Fielding 氏が 2000 年に発表した論文で提唱されました。当時、Web の成長によってシステムを統合する必要性が高まり、分散システムに適した可用性や拡張性の高い設計が必要となったようです。
REST は RFC として標準化されているわけではありませんが、Fielding 氏の論文やその後の解説や実践に基づいた一定の原則や制約があります。これらの原則や制約に従った設計を「RESTful」と呼びます。
REST の原則
原則はいくつあるのか
日本語版の Wikipedia では、「４つの原則」が挙げられています。
- ステートレスなクライアント/サーバプロトコル
- すべての情報（リソース）に適用できる「よく定義された操作」のセット
- リソースを一意に識別する「汎用的な構文」
- アプリケーションの情報と状態遷移の両方を扱うことができる「ハイパーメディアの使用」
しかし、先述の論文では「4 つの原則」ではなく、6 項目の特徴が挙げられています。
- Client-Server
- Stateless
- Cache
- Uniform Interface
- Layerd System
- Code-On-Demand
なぜ解説にズレが生じるのでしょうか。調べていくと「RESTful Web Services」という書籍が参考になりそうでした。本書で提唱されているリソース指向アーキテクチャの 4 つの特性が、日本語版 Wikipedia の内容と類似しています。我々の認識している「4 つの原則」というのはここから来ているのではないかと思われます。
- Statelessness（ステートレス性）
- Uniform Interface（統一インターフェース）
- Addressability（アドレス可能性）
- Connectedness（接続性）
書籍「RESTful Web Services」
Leonard Richardson 氏, Sam Ruby 氏によって 2007 年に出版された書籍です。
日本語訳版の冒頭部分を引用させて頂きます。
残念ながら、これまでのところ、REST の主要な文献は、Roy Fielding の 2000 年の博士論文の第 5 章であった。
（中略）
REST に関するその他ほとんどの情報源は、メーリングリスト、Wiki、ブログなど、非公式のものである。REST のベストプラクティスは、これまでのところ、伝承くらいのものである。私たちに必要なのは、REST メタアーキテクチャに基づいた具体的なアーキテクチャである。つまり、Web の潜在能力を引き出す標準的なサービスを実装するための、シンプルなガイドラインである。本書では、そうしたアーキテクチャの 1 つを、ROA として紹介する。
このように、本書では REST をガイドラインとしてまとめ、それに基づく設計思想として、ROA (リソース指向アーキテクチャ) を提唱されています。
ROA（リソース指向アーキテクチャ）について
ROA（リソース指向アーキテクチャ）とは
名前の通り「リソース」に重点を置いたアーキテクチャで、RESTful な設計思想です。
リソースは ROA だけでなく REST において最も重要な概念です。リソースとは、サービスが提供する「もの」を指します。
ROA の特徴は、RPC (Remote Procedure Call) との設計思想に違いを見るとわかりやすいです。
- RPC は「操作」に重点を置いています。
- ROA は「リソース」に重点を置いています。
ROA は RESTful の定義そのものであるようにも受け取れますが、あえて「リソース指向アーキテクチャ」と名付けたのには理由があるようです。「Restful Web Services」によると、REST には標準仕様がないことから慣習で補われた部分も多く、「RESTful を定義しよう」とすると議論が発散してしまう恐れがあるため、別の名前を付けることにしたとのことです。
リソースの表現
リソースを定義する明確な基準はないため、設計においては「API で操作する対象とすべきかどうか」を考えます。
リソースは名詞で表現します。しかし、現実的には全てがモノであるとは限らないため、概念やアイデアなどの抽象的なものでも「リソース」として扱います。
例えば、言語翻訳サービスにおいて「翻訳する」機能を API で提供したい場合、「翻訳する」は動詞です。ここでは、「翻訳」という概念をリソースと捉えて /translations と表現することができます。翻訳の内容をパラメータで渡すことで、翻訳処理を行うなどが考えられます。（これは説明のための一例です。）
ROA の 4 つの特性
ROA は以下の 4 つの特性を備えるべきとされています。
- アドレス可能性（Addressability）
- ステートレス性（Statelessness）
- 統一インターフェース（Uniformed Interface）
- 接続性（Connectedness）
アドレス可能性
アドレス可能性とは、リソースを URI で一意に識別して、API としてアクセス可能であることを指します。
この特性によって、プログラムから接続できるようになり、分散システムを構成することが可能になります。
この特性がない場合、GUI でしか操作できないなど、API としての価値が成り立っていないため、最も基本的な特性となります。
ステートレス性
ステートレス性は、全てのリクエストが個別に処理され、リクエスト間の依存性がないことを指します。
この特性によって、アプリケーションの拡張が容易になり、リトライなどの対策も取れるため、システムとしての信頼性が高まります。
この特性がない場合、サーバ側で状態を維持管理することを意味するため、拡張性がなく不安定なシステムになってしまいます。
統一インターフェイス
統一インターフェースは、すべてのサービスが HTTP のインターフェースを同じ方法で使用することを指します。
この特性によって、異なるサービス間でのインターフェースが混在することがなく、統一的なやりとりが可能になります。
この特性がない場合、個々のサービスで見れば、操作に対して相応しい名前をつけた方が理解しやすいと思われるかもしれません。しかし、「どのリソースであっても GET は読み取りを意味する」という統一性を持たせることで、よりシンプルに API を表現することができます。
接続性
接続性は、他の 3 つの特性を兼ね備えた上で、関連するリソースの URI をお互いに表現することを指します。
この特性によって、クライアント側が URI の生成ルールを把握する必要がなく、関連するリソースにアクセスすることが可能になります。
この特性がない場合、URI を知る術がなくリソースにたどり着けません。
REST 以外の API 設計手法
REST が発表されてから 20 年以上が経過し、当然ながら技術動向も大きく変化しています。そのため、REST 以外の設計手法にも注目しておくべきです。
現在、REST に対抗する代替手法として gRPC や GraphQL が存在し、それぞれ独自の利点を持っています。
当初は、RPC のようなメソッド指向のインタフェースで分散システムを構成することの複雑性という課題感から、シンプルで柔軟な REST が登場しました。 ここでいうシンプルさは、「リソースを定義し、HTTP メソッドで操作する」という一貫性を保つことによる「汎用性」と捉えることができます。
しかし現在、マイクロサービスによる通信の増加や複雑さによって、汎用性よりも応答性能を重視したい場合もあるでしょう。そのような状況において、gRPC や GraphQL は有効な選択肢となります。マイクロサービスにおけるフロントとBFFとの通信など、それ専用と言えるインタフェースは代表例と言えます。これらの通信手法は必ずしもシステム全体でどれかひとつに統一すべきものではなく、状況に応じて適切に選択することができます。
いずれにしても、REST は現代においても有効な API 設計手段です。設計や実装がシンプルで理解しやすく、HTTP プロトコルを採用していることから、外部に公開する API の仕様としても適していると言えます。
まとめ
本記事では、API 設計において重要な考え方である REST とリソース指向について解説しました。
まず、REST の基本的な考え方や特徴、リソース指向について解説しました。また、RESTful API を実装するための原則などの基礎的な知識をまとめました。
そして、REST 以外の API 設計手法として、gRPC や GraphQL についても取り上げました。これらはどれかひとつに固執することなく、状況に応じて選択することができます。REST はこの中でも歴史のある技術ですが、現代においても有効な API 設計手段であることもわかりました。
最後に、つまりリソース指向に則って API を設計するとは何をどうすることをいうのかを端的にまとめます。
- API として公開すべき「リソース」を定義して命名し、URI で表現する
- 「リソース」に対して、どの HTTP メソッドの操作を提供するかを決める
- リクエスト／レスポンスとして必要な表現を定義し、ステートレスかつ安全／冪等に実装する
さいごに
みらい翻訳では、エンジニアを募集しています。
ご興味のある方は、ぜひ下記リンクよりご応募・お問い合わせをお待ちしております。
