Microsoft REST APIガイドラインはRESTfulではない

Microsoftが「RESTful」なAPIを作成するためのガイダンスを公開した。Roy Fielding氏は、そのAPIを (RESTとほとんど関係ない) HTTP APIと見なしている。

多くの組織が、Web向けのHTTP APIを作成するための推奨を公開している。米国ホワイトハウスでさえ、ホワイトハウスWeb API標準 (White House Web API Standards) で標準を公開している。Microsoftは、最近、完全で成熟した仕様であるMicrosoft REST API ガイドライン2.3 (Microsoft REST API Guidelines 2.3) を公開した。このガイドラインは、主にAzureチームによってクラウドサービスの構築作業で開発、使用されている。

ここで、我々はドキュメントの完全な説明については興味がある読者に任せ、MicrosoftのAPIガイドラインからいくつかの主なポイントを要約する。

• クライアントライブラリを必要とすることなしに、APIの採用を促進するために、URLは人にとって可読性が高く構築可能であるべきである。
• HTTP動詞としてGET、PUT、DELETE、POST、HEAD、PATCH、OPTIONSがサポートされる。全てのリソースが全ての動詞をサポートすべきというわけではない。
• GET、PUT、DELETE、HEADは冪等 (べき等、idempotent) であるべきである。
• カスタムヘッダが必須であってはいけない。
• PII (個人情報、Personally Identifiable Information) がログファイルを通して公開される可能性があるので、クライアントは、URL内でPIIを転送すべきではない。パラメータはヘッダを通して渡されるべきである。
• データは、人気の高いフォーマットで提供されるべきである。
• デフォルトのデータエンコーディングは、JSONである。
• プリミティブ値は、RFC 4627の規則に従って、JSONでシリアライズされなくてはならない。
• APIを使う開発者は、好みの言語とプラットフォームを使えるべきである。
• サービスは、curlのような単純なHTTPツールからでさえもアクセス可能であるべきである。
• APIは、明示的なバージョニングをサポートすべきである。
• サービスは、可能であれば、破壊的変更を導入することなく安定的であるべきである。しかし、必要な場合には、破壊的変更の導入が許されるべきであり、破壊的変更を示すためにバージョン番号を増やす。
• バージョニングは、「メジャー.マイナー」スキームを使って行われるべきである。
• サービスは、Webhook (HTTPコールバック) を介して、プッシュ通知を実装しても構わない。

このガイドラインは、適切に構造化されたURLだと考えられているものの例を提供している。

https://api.contoso.com/v1.0/people/jdoe@contoso.com/inbox

そして、これが避けるべきURLの例である。

https://api.contoso.com/EWS/OData/Users('jdoe@microsoft.com')/Folders('…[非常に長い識別子]…=')

MicrosoftのREST API向けのガイドラインが公開された直後、REST、HTTP/1.1の作者でありApacheソフトウェア財団 (Apache Software Foundation) の共同創立者であるRoy Fielding氏が、このガイドラインに対する次のような不満を表明した。「RESTの最悪の説明でさえも、[Microsoft/api-guidelines] で示されている内容よりずっと優れています」。InfoQは、Fielding氏がこのガイドラインに満足していない理由の詳細を知るために、彼に連絡した。彼の返信をすべて公開する。

私は、Microsoftのような企業が、内部のドキュメントや開発ガイドラインをパブリックなフォーラム、特にGitHubのようなオープンな協力の場に公開する決断をしたことは、素晴らしいと考えています。パブリックな会話に対するオープンさは、我々全てが業界内で作業する方法を大幅に改善するでしょう。

このガイドラインで私が気に入らないのは、これがMicrosoftエコシステムの中で適切なHTTP APIを開発する方法に関するまとめなのに、REST API、RESTful APIだとされている点です。RESTに関する関連資料をざっと読めば明らかなように、RESTはHTTPではありません。このガイドラインは明らかにRESTを基にしておらず、(RFC 7231によって取って代わられたRFC 2616の一部を除いて) 私の仕事を参照しようとすらしていません。これは、SOAP/RPCインタフェースのある種のHTTPバージョンとしてRESTを説明するという、以前に深くWebサービスの世界にいた人々によくある間違いです。

実際にこの間違いがどんなによくあるものだとしても、RESTのふりをすることはできません。RESTアーキテクチャスタイルの性質のほとんどは、過去の失敗したツールに都合よく似ている制約だけではなく、RESTアーキテクチャスタイルの制約の全てを守ることから来ています。もし、HTTPを使ってRPCを構築したいだけの人々がそれをHTTP APIと呼ぶならば、私はその人々に異存はありません。それはRESTではありません。それはWebからのものではありません。これは、HTTPを使ったRPCをHTTPサービスとして説明、実装できない、という意味ではありません。HTTP APIをそういったものとして理解し、間違ったバズワード (流行語) に従う必要性を感じることなく、その実装ガイドラインを議論することに、価値があります。

多くのWebサービスプロバイダがHTTP APIを作成し、それを使うことに非常に成功している。クラウドコンピューティングのほとんどは、こういったAPIを基にしている。なぜ、多くのプロバイダが、APIが「RESTful」ではないのに「RESTful」だと主張しているのかは、依然として謎である。この問題についてさらに興味がある方には、InfoQの記事であるWhy Some Web APIs Are Not RESTful and What Can Be Done About It (なぜRESTfulではないWeb APIがあり、それについて何ができるか)、 Roy Fielding on Versioning, Hypermedia, and REST (バージョニング、ハイパーメディア、RESTについてRoy Fielding氏に訊く) をお勧めする。