tkawaのはてぶろ。

一昨年からだいたい月1回ぐらいのペースで、Webの基本的な仕組みを基礎から学ぶ「RESTful#とは勉強会」を開催しています。主催はshokolaさんで、私は進行役を担当しています。

2月23日に開催したRESTful#とは勉強会13では、ヴァル研究所さんの協力のもと、駅すぱあとWebサービスをレビューするという企画をやりました。いろんな意見が出てとてもおもしろかったです。みなさんありがとうございました。

ゲストとして来ていただいた@Keisuke69さんがブログ記事を書いておられたので、これは私も書かなければ、ということで感じたことを書いていきます。

keisuke69.hatenablog.jp

駅すぱあと Webサービスについて、当日思っていて言い忘れたこと

トークンをURLのクエリパラメータにつける方式になっていますが、それならHTTPS必須にしたほうがよい
API実装の改良の理由としてパフォーマンスを挙げておられましたが、内部の通信にHTTPを使っているのであればそこを別のプロトコルに変えたほうがパフォーマンスが上がりそう
リンクをつけるととても使いやすくなります（後述）

RESTfulにする理由

「当日参加者からもあがったRESTfulである必要性や、RESTの一般的なルールをどこまで守る必要があるかについて個人的な見解」を私も考えてみました。

APIをRESTfulにすべきかどうかは、目的や手段によるわけですが、その中でもHTTPを使うかどうかに大きく左右されると思います。RESTの制約の大部分はおおざっぱに言えば「HTTPのルールを守る」と言い換えてもよいものであって、HTTPを使うのであればHTTPのルールを守ったほうが良いものができるのは当然のことです。SOAPが衰退したのは、HTTPを使いつつルールを完全に無視したことも一因でしょう。

RESTの枠にURL, HTTP, HTMLが入る

今回議論に上がったURLの規則やネーミングについては、実はHTTPのルールと関係ありませんし、「狭義のREST」には含まれません。「広義のREST（あるいはROA）」として、また設計のパターン化としてはメリットのあるものだと思います。

では、RESTful APIとしてもっと重要な本質的なこととは何でしょうか？ 1つは作りたいAPIのドメイン（今回の場合鉄道・交通など）にふさわしい表現を設計することですが、もう1つ挙げると「狭義のREST」の中で完全に無視されている「ハイパーメディア制約」です。

ハイパーメディア制約とは、簡単に言うとリンクを作ることです。今回のAPIは、「駅情報検索→経路検索→時刻表」のように遷移のパターンが非常にわかりやすいAPIです。このようなときこそ、リンクが活きます。レスポンスの中に次に遷移する候補のリンク(URL)を含めておけば、クライアントはそれをたどることで容易に結果を得られます。URLが変わっても問題ありません。

Web APIが変に難しく考えられているところはあって、「Webを支える技術」で何度も書かれている通り『WebサービスとWeb APIを分けて考えない』これが一番重要なんです。Webアプリ（サイト）を作るのと同じようにWeb APIを作ればいい。HTMLかJSONかが違うだけ。
— Toru KAWAMURA (@tkawa) February 23, 2016

と言ったのはこのハイパーメディアの意味でもあります。Webアプリ（サイト）を作るときには必ずリンクを作りますよね。Web APIでも同じです。

Web APIはただのデータだと思っていると、リンクの必要性が感じられないかもしれません。しかし、HTTPを使う以上、RESTfulにすることがメリットを最大限活かす方法であって、そのためにはハイパーメディアは欠かせないものです。

Web API アクセシビリティ

さらに先の話になりますが、最近考えているのは「Web API アクセシビリティ」です。（これは勝手に作った用語なので、英語としては本来の用法からずれているかもしれません）

Webアクセシビリティと言ったとき、今まではWebアプリ・Webページに対して必要であるとされてきました。例えばHTMLの img に対して alt 属性をつける、といったことです。Webアプリに対してはWAI-ARIAがあります。これは一面としてセマンティクス＝「意味の情報」の付加であるととらえることができます。

ARIA は Web アプリケーションやウィジェットを、スクリーンリーダーや拡大鏡といった支援技術を使用するユーザを含む幅広いユーザに対してアクセシブルにする手段を提供します。 ARIA はメニュー、スライダー、ツリー、ダイアログといった多くの一般的なユーザインターフェイスの役割、状態、機能性を示す付加的な意味を与えます。また作者がページ上の目印、部分、グリッドを設定することを支援する、付加的な構造情報も与えます。 https://developer.mozilla.org/ja/docs/Web/Accessibility/ARIA/Web_applications_and_ARIA_FAQ

ユーザにとって使いやすくするために、コンピュータが理解できる「意味の情報」を加えるということです。結果として、コンピュータにとっても使いやすくなり、自動処理や再利用がしやすくなります。

そこで昨今のWeb APIを見てみると、セマンティクスがあまりに足りない。ユーザのためのAPIドキュメントがかろうじてありますが、それも別のところに置いてあるだけで、APIの中身を見てもわかりません。到底アクセシブルとは言えない状況です。

Web APIをアクセシブルにするための方法は、まだ決まったものがありません。OpenAPI(Swagger)、API Blueprint、RAMLなどは、近いところもありますが、RESTの制約である「自己記述的」を満たしていないこともあり、現状は少し方向が違うのではと思っています。具体的にはメディアタイプやプロファイルの活用ということになると思いますが、これからも考えていきたいです。メディアタイプやプロファイルについては「RESTful Web APIs」で詳細に説明されていますので、ぜひ読んでみてください。