APIがRESTfulであるとはどういうことか
What it means for an API to be RESTful (en.andros.dev)
要約
RESTful APIは、単にJSONを返すHTTP APIではなく、Roy Fieldingが定義したアーキテクチャスタイルであるRESTの制約(クライアント・サーバー、ステートレス、キャッシュ可能、レイヤードシステム、統一インターフェース、コードオンデマンド)に従うものです。特に、HATEOAS(Hypermedia as the Engine of Application State)により、APIは自己記述的でナビゲート可能になります。真にRESTfulなAPIは、リソース識別子、プロトコルの標準、メディアタイプ、そしてハイパーメディア(リンク)に焦点を当て、外部ドキュメントに依存せず、クライアントがAPIを探索できるようにします。
全文翻訳
APIがRESTfulであるとはどういう意味か
RESTful APIとは何か、あなたは知らないかもしれません。あらゆる種類のAPIを統合し、複数の言語で本番稼働しているAPIを多数持つ、経験豊富な開発者であることは承知しています。しかし、それらはすべて、業界のベストプラクティスに従い、計り知れない量のドキュメントを読んだことを証明するに過ぎず、それは良いことです。しかし、RESTfulに関するあなたの知識を証明するものではありません。パニックになる必要はありません!あなたは一人ではありません。私が知っている開発者のほとんどは、それを定義したり、実装したり、その強みを指摘したりできません。だからこそ、この記事では、理解しやすい例でその美徳を説明します。そして、読み終わったら、APIの見方が変わるかもしれません。警告しておきます!
API RESTfulは、REST API(Representational State Transfer)の同義語としてよく使われますが、そのニュアンスは重要です。RESTはHTTPインターフェースではありません。それは、Roy Fieldingが2000年の博士論文で定義したアーキテクチャスタイルであり、制約を課します。
- クライアント・サーバーアーキテクチャ:クライアントとサーバーは分離されなければなりません。
- ステートレス:サーバーへの各クライアントリクエストには、リクエストを理解し処理するために必要なすべての情報が含まれていなければなりません。言い換えれば、サーバーはリクエスト間でクライアントの状態に関する情報を保持しません。
- キャッシュ可能:レスポンスは、キャッシュ可能またはキャッシュ不可能として明示的にマークされなければなりません。
- レイヤードシステム:アーキテクチャはレイヤーで構成でき、各レイヤーは特定の機能を持ち、互いに分離されています。
- 統一インターフェース:クライアントとサーバー間の通信は、明確に定義されたパターンで予測可能でなければなりません。
- コードオンデマンド(オプション):サーバーは、JavaScriptスクリプトなどの実行可能なコードをクライアントに送信して、クライアントの機能を拡張できます。
言い換えれば、RESTは、通常HTTP経由でリソースを提供するためのアーキテクチャ原則のセットです。それはWeb開発に深く根ざしており、非常に標準化されているため、それが見られないと奇妙に感じられます。
そして、ここに不快な部分があります。厳密に言えば、RESTはすでにこの記事でこれから読むすべてを含んでいます。ハイパーメディアは統一インターフェース制約の一部であり、「RESTful」は単なる形容詞、「RESTに準拠している」という意味です。起こったことは、一般的な用法が「REST」を「JSONを返すHTTP API」という意味に劣化させてきたことです。Fielding自身が2008年に、HTTPで着飾ったRPCをRESTと呼ぶことを不満に思う有名な記事「REST APIs must be hypertext-driven」を公開したほどです。Richardson Maturity Modelは、その距離に数値をつけました:レベル0、単一のRPCスタイルのエンドポイント;レベル1、独自のURIを持つリソース;レベル2、HTTP動詞とステータスコードが正しく使用されている;レベル3、ハイパーメディア。あなたが毎日利用する「REST」APIの大多数はレベル2に留まっています。
この記事では、Fieldingが要求するレベル3、つまりレベル3を指すためにRESTfulを使用します。目標は、APIを予測可能で標準化された自己記述的なインターフェースに変えることです。ベースURLだけで、クライアントは外部ドキュメントに頼ることなく、すべてのリソースを探索できるようになります。さらに、ルートを変更してもクライアントに影響を与えずに柔軟に対応したり、複数の通信プロトコルを使い分けたりすることもできます。
しかし、まず知っておくべき概念があります:HATEOAS(Hypermedia as the Engine of Application State)です。この概念は、RESTful APIがどのように自己記述的でナビゲーション可能であるかを理解する上で不可欠です。
HATEOAS(Hypermedia as the Engine of Application State)
ハイパーメディアはRESTfulの重要な特徴の1つです。これにより、クライアントはレスポンスで提供されるリンクを通じてリソースを動的に発見できます。通常、これらは_links親の下にあります。
{
"id": 123,
"name": "John Doe",
"_links": {
"self": {
"href": "/users/123",
"method": "GET"
},
"update": {
"href": "/users/123",
"method": "PUT"
},
"delete": {
"href": "/users/123",
"method": "DELETE"
},
"friends": {
"href": "/users/123/friends",
"method": "GET"
},
"posts": {
"href": "/users/123/posts",
"method": "GET"
},
"search": {
"href": "/search/?query={query}",
"method": "GET",
"templated": true
}
}
}
これにより、クライアントはインターネットを閲覧するように、リンクを解析してたどることでAPIをナビゲートし、必要な情報に到達できます。さらに、オブジェクトキーを識別子として相対ルート(href)間を移動するため、バックエンドはアドレスを変更してもクライアントに影響を与えずに済みます。クライアントは固定されたルート構造に縛られず、ノード間を移動するため、これは非常に強力です。
最後のリンクでtemplated: trueが使用されていることに注意してください。これは、hrefにURIテンプレート(RFC 6570に準拠)が含まれており、使用前に特定の値を埋め込む必要があることを示しています。これは、パラメータ化されたエンドポイントを発見するためのエレガントな方法です。たとえば、クライアントは{query}を「restful api」に置き換えて、関連コンテンツを検索できます。
先に進む前に正直な注意点があります。_links規約はHAL(Hypertext Application Language)に由来しますが、HALはmethodフィールドを定義していません。そのリンクはhref、templated、type、またはtitleのようなプロパティのみを考慮します。私はそれを追加します。なぜなら、実際にはAPIが自己記述的になるのに役立ち、一般的な拡張だからです。正式なメソッドとフィールドを持つアクションが必要な場合は、Sirenを参照してください。純粋なHALを好む場合は、methodを省略し、プロトコルの規約(ルール2)を信頼してください。
すべてのリソースにハイパーメディアが必要なわけではありません。適切なコンテキストを持つ関連性の高いリソースのみが必要です。たとえば、ブログ記事にショッピングカートへのリンクを含めるのは意味がありませんが、記事に著者、コメント、または関連記事へのリンクを含めるのは興味深いでしょう。
HATEOASの重要性を理解したので、RESTful APIが従うべきルールを見てみましょう。
RESTful APIの6つのルール
これらのルールは私が勝手に決めたものではありません。これらは、私が言及した記事でFieldingがリストした6つの条件であり、ここでは例とともに適応されています。
1. 単一のプロトコルに依存しない
リソース識別子(URI)を使用してリソースを定義します。つまり、URL(http://example.com/api/users/123)を使用する代わりに、その場所を示し、プロトコルを無視するURI(/users/123)を使用します。これにより、WebSocket、MQTT、NNTP、RPCなど、他のプロトコルも使用できます。もちろんHTTPを使用できますが、それにのみ依存してはなりません。たとえば、APIがHTTP専用に設計されている場合、厳密にはRESTfulではありません。
2. プロトコルを変更しない
車輪の再発明をしないでください。プロトコルで創造的にならないでください。たとえば、HTTPを使用する場合は、規約に従ってください:GETはリソースの取得、POSTは作成、PUTは置換、PATCHは部分更新、DELETEは削除に使用します。適切なHTTPレスポンスステータスを使用してください:200 OK、201 Created、204 No Content、400 Bad Request、404 Not Foundなど。MQTTを使用しますか?適切なコマンドとステータスを使用してください。
3. メディアタイプに焦点を当て、URIではない
各URIを外部で文書化するのではなく、APIが処理するメディアタイプを記述する必要があります。これは6つのルールのうち最も誤解されているルールであり、Fieldingにとって、ほぼすべての記述的な努力を注ぐべき場所です。アイデアは、ルートのリスト(通常「ドキュメント」と呼ぶもの)を公開するのではなく、メディアタイプ(たとえばapplication/vnd.myshop.product+json)を定義および文書化することです。つまり、各表現のフィールドの意味と、そのリンクの処理方法です。クライアントは、呼び出したURIではなく、受信したContent-Typeに基づいて何をするかを決定します。URIは交換可能な詳細になります。
たとえば、情報が少ないユーザーのリソースは次のようになります。
{
"id": 123,
"name": "John Doe",
"_links": {
"self": "/users/123",
"friends": "/users/123/friends",
"lastInvoice": "/users/123/invoice/last"
}
}
より多くの情報を持つユーザーのリソースは次のようになります。
{
"id": 123,
"name": "John Doe",
"_links": {
"self": {
"href": "/users/123",
"method": "GET",
"type": "application/json"
},
"friends": {
"href": "/users/123/friends",
"method": "GET",
"type": "text/csv"
},
"lastInvoice": {
"href": "/users/123/invoice/last",
"method": "GET",
"type": "application/pdf"
}
}
}
4. URI構造を推測しない
クライアントでURI構造を保存したり再利用したりしてはなりません。APIはそれらを予告なく変更する可能性があり、クライアントは明らかに動作しなくなります。代わりに、リンクを解析し、相対識別子(rel)をたどってください。
リソースは次の構造を持つことができます。
{
"id": 987,
"name": "Totoro plush",
"price": 19.99,
"_links": {
"self": {
"href": "/products/987",
"method": "GET"
},
"addToCart": {
"href": "/cart/add/987",
"method": "POST"
},
"reviews": {
"href": "/products/987/reviews",
"method": "GET"
}
}
}
そして翌日:
{
"id": 987,
"name": "Totoro plush",
"price": 19.99,
"_links": {
"self": {
"href": "/shop/item/987",
"method": "GET"
},
"addToCart": {
"href": "/shop/cart/987",
"method": "POST"
},
"reviews": {
"href": "/shop/item/987/reviews",
"method": "GET"
}
}
}
5. リソースの「タイプ」を避ける
APIでリソースの階層、権限、またはタイプを公開しないでください。クライアントは気にしませんし、知るべきでもありません。たとえば、/users/admin/123や/users/guest/123のようなリソースを持つべきではありません。代わりに、リンクを使用してリソースに対して実行できるアクションを定義してください。
6. ブックマーク(ルートリソース)から始め、クライアントに探索させる
クライアントはルートURL(またはブックマーク)から開始し、そこからAPIユニバースをナビゲートします。
{
"message": "Welcome to my RESTful API",
"_links": {
"users": {
"href": "/users",
"method": "GET"
},
"products": {
"href": "/products",
"method": "GET"
},
"orders": {
"href": "/orders",
"method": "GET"
},
"search": {
"href": "/search/?query={query}&page={page}",
"method": "GET",
"templated": true
},
"user-by-id": {
"href": "/users/{user_id}",
"method": "GET",
"templated": true
},
"product-search": {
"href": "/products/search/?name={name}&category={category}",
"method": "GET",
"templated": true
}
}
}
複数のリンクがHATEOASセクションで見たURIテンプレートであるtemplated: trueを使用していることに注意してください。クライアントは、レスポンスから離れることなく、パラメータ化されたエンドポイントさえ発見します。
これで、RESTful APIの構築方法について一般的なアイデアが得られました。RESTの原則、RESTful APIのルール、HATEOASの概念の間で、堅牢なAPIを構築できるようになります。
FAQ
APIまたはエンドポイントのバージョンを示すにはどうすればよいですか?
最も一般的なアプローチは、URLにバージョンを含めることです。たとえば、/api/v1/usersです。しかし、RESTfulルールに従いたい場合は、URIからバージョンを削除する必要があります。最も推奨されるオプションは、Acceptヘッダーを使用してapplication/vnd.example.v1+jsonという構造でネゴシエートすることです。ここで、exampleはAPIの名前、v1はバージョンです。
たとえば、私のAPIはdreamと呼ばれ、最新バージョンは2.1なので、ヘッダーは次のようになります:Accept: application/vnd.dream.v2.1+json。
別の簡単なオプションですが、あまり推奨されませんが、Api-Versionのようなカスタムヘッダーを使用し、その値は2.1になります。ただし、古典的なX-プレフィックス(X-API-Version)は避けてください。これはRFC 6648によって2012年から非推奨になっています。
ページネーションを処理するにはどうすればよいですか?
ページネーションを示すメタデータレスポンスに含める必要があります。
ページネーションの例は次のようになります。
{
"data": [...],
"meta": {
"total": 150,
"page": 1,
"perPage": 10,
"hasNext": true,
"hasPrevious": false
},
"_links": {
"self": {"href": "/api/items?page=1", "method": "GET"},
"next": {"href": "/api/items?page=2", "method": "GET"},
"first": {"href": "/api/items?page=1", "method": "GET"},
"last": {"href": "/api/items?page=15", "method": "GET"}
}
}
ここで:
total:利用可能なアイテムの総数。現在のページではなく、コレクション全体です。page:現在のページ番号。0または負の値にすることはできません。perPage:ページあたりのアイテム数。hasNext:次のページが利用可能かどうかを示します。hasPrevious:前のページが利用可能かどうかを示します。_links:next、previous、first、last、selfのようなページネーションをナビゲートするためのリンク。リンクが適用されない場合(最初のページに前のページがない場合)、それは省略され、nullに設定されません。HALはそれをそのように行い、クライアントのあいまいさを回避します。
クライアントがページ番号を指定できるようにテンプレートを使用することもできます。
{
"_links": {
"page": {
"href": "/api/items?page={page}&perPage={perPage}",
"method": "GET",
"templated": true
}
}
}
エラーを処理するにはどうすればよいですか?
ここに標準がありますが、ほとんどの人はそれを知りません:RFC 9457(HTTP APIのProblem Details。2016年のRFC 7807を更新)。これは、5つのフィールドを持つapplication/problem+jsonメディアタイプを定義します:type(問題カテゴリを識別するURI)、title(短く安定した要約)、status(HTTPステータスコード)、detail(この特定の発生の説明)、およびinstance(影響を受けるリソースのURI)。そして、独自の拡張フィールドを追加できます。
たとえば、404 Not FoundステータスとContent-Type: application/problem+jsonヘッダーを持つレスポンスは、このボディを運びます。
{
"type": "https://example.com/errors/article-not-found",
"title": "Article not found",
"status": 404,
"detail": "There is no article with id c9bb4e4a",
"instance": "/api/blog/c9bb4e4a"
}
ゼロからAPIを開始する場合、私のアドバイスはProblem Detailsを使用することです。これは標準であり、クライアントは感謝するでしょう。私のプロジェクトでは、ユースケースのレスポンス構造と統合される独自の規約(type、errors、data、meta)を使用しています。興味がある場合は、Implementing Clean Architecture in Pythonで説明しています。
結論
Fieldingが説明した真のRESTful APIは、RESTの進化ではありません。それは完全なRESTであり、ほとんど誰も到達しないRichardson Maturity Modelのレベル3です。一般的な用法はリソース、動詞、ステータスコードで止まりますが、ハイパーメディアはAPIを自己記述的でナビゲーション可能なインターフェースに変えるものを追加します。
エラーについては、すでに標準であるRFC 9457があります。それを使用すれば、クライアントは常に期待されるものを知ることができます。
要するに、適切に実装されたRESTful APIは単にデータを転送するだけではありません。クライアントをすべてのリソースに手を取り、直感的で変更に強い体験を創造します。これは長期プロジェクトにとって不可欠です。
ソース
トピックをさらに掘り下げたい場合は、いくつかのおすすめのソースを以下に示します。
- Roy Fielding's Dissertation
- Roy Fieldingによる「REST APIs must be hypertext-driven」
- Martin Fowlerによる「Richardson Maturity Model」
- RFC 9457: Problem Details for HTTP APIs
- HAL - Hypertext Application Language
- Lokesh Guptaによる「REST Architectural Constraints」
HALとJSON-LDについてさらに読むことも興味深いでしょう。これらは、HATEOASとRESTful APIの自己記述を容易にするフォーマットだからです。