『Web API Design -Crafting Interfaces that Developers Love-』の翻訳①

*作成中ですが、諸事情により一時的に公開*

Introduction

これを読んでいるのなら、おそらくあなたは開発者に愛されるWeb APIのデザインについて関心があり、証明されたデザインの原則とベストプラクティスを自身のWeb APIに適用することに興味があるのだろう。

我々のデザイン思考の元となるものの一つは、RESTである。RESTはアーキテクチャスタイルの一つであり、厳格な規格ではないため、非常に柔軟性がある。その柔軟性と構造の自由さにより、ベストプラクティスのデザインに対する大きな欲求もまた存在するのである。

この電子書籍は、我々がこれまで世界中の優れたAPIチームと協力して開発してきたデザインのプラクティス(実践)を集めたものである。彼らAPIチームは、我々がApigeeで提供するデザイン・ワークショップを通して、自身らのAPI戦略を作り上げている。

我々は、APIデザインにおける我々の視点を”pragmatic REST(実用的なREST)”と呼んでいる。これは、デザインの原則よりも、開発者の成功を優先するためである。開発者こそが、Web APIの顧客なのである。APIデザインの成功は、あなたのAPIを使うことで、開発者が成功を享受することを加速し、始めるに至るまでをどれだけ早めることができるかによって評価される。

我々は、あなたのフィードバックを必要としている。賛成か、反対か、付け加えるべきプラクティスやティップスがあるかどうか。API Craft Google Groupは、Web APIデザインの熱狂者が集まり、デザインのプラクティスについて議論し、共有する場所である。そこでぜひ、あなたとお会いしたい。

Are you a Pragmatist or a RESTafarian?

APIデザインについての我々の全般的な観点から始めよう。我々はdogmaticな(教義上の)RESTではなく、pragmaticな(実用的な)RESTを推奨する。我々の言うdogmaticとは何を意味するのか?

あなたは正確なRESTについてについて議論するスレッドを見たことがあるかもしれない。中には、とても厳格で生真面目なものもある。Mike Schinkelは、RESTafarianを以下のように定義して、うまくまとめている。

RESTafarianは、Roy T. FieldingがUC Irvine(カリフォルニア大学アーバイン校)で提出した博士論文の第5章で定義したRESTソフトウェアアーキテクチャスタイルの熱狂的な支持者である。あなたはREST-discuss mailing listで、野生のRESTifarianを見つけることができる。しかし注意してほしい。RESTifafianはRESTの細部について議論するとき、ひどく細かいところに拘るのだ…

我々の観点はこうである。「裏返し」の視点からAPIデザインにアプローチする。これはすなわち、我々は次のように尋ねることから始めるということである。「我々はAPIを使って何を達成しようとしているのか?」

APIの役割は、開発者を出来る限り成功させることである。APIの方向付けは、アプリケーション開発者の観点からデザインの選択について考えるということである。

なぜか?以下のバリューチェーン(価値連鎖図)を見てほしい。アプリケーションの開発者が、API戦略全体の要である。あなたのAPIを作り上げるときの主要なデザイン原則は、開発者の生産性と成功を最大化するものであるべきである。これが、我々がpragmatic REST(実用的なREST)と呼ぶものである。

Pragratic RESTは設計の問題である

あなたは設計を正確なものにしなくてはならない。というのも、デザインは、モノがどのように使われるかを伝えるものだからである。ここで疑問となるのは、アプリの開発者にとって最適で利益のあるデザインがどのようなものか?ということである。開発者の観点は、我々が集めたすべての具体的なティップスとベストプラクティスに対する原則を導くものである。

Nouns are good: verbs are bad

実用的なRESTfulデザインの一つ目の原則は、「シンプルなものをシンプルなままにする」ということである。

Keep your base URL simple and intuitive

ベースURLは、あなたのAPIの最も重要なデザイン・アフォーダンスである。シンプルで直感的なベースURLのデザインは、あなたのAPIを使いやすくしてくれる。

アフォーダンスはデザインの特性であり、モノがどのように使われるべきかを、ドキュメンテーションなしで伝えるものである。ドアの取っ手のデザインは、引くか押すかを伝えるものであるべきある。ここに、デザイン・アフォーダンスとドキュメンテーションが衝突してしまっている例を示そう。直感的なインタフェースではない!

我々がWeb APIデザインのために使う重要なリトマス試験は、一つのリソースにつき2つのベースURLのみが存在するかどうかである。シンプルなオブジェクト(もしくはリソース)としてdogについてのAPIのモデルを作り、Web APIを作成してみよう。

最初のURLはコレクションのためのもので、二つ目はコレクションの中の特定の要素のためのものである。

/dogs     /dogs/1234

このレベルまでURLを要約することは、あなたのベースURLから動詞を追い出すことにもなるだろう。

Keep verbs out of your base URLs

多くのWeb APIは、URLのデザインに対して、メソッド・ドリブンのアプローチを使うことから始めている。これらのメソッド・ベースのURLは、その始まりや終わりにおいて、動詞を含むことがある。

我々のdogのように、あなたがモデル化するどのようなリソースにおいても、あなたは一つのオブジェクトを孤立したものと見なしてはいけない。それどころか、オブジェクトを構成するために常に関係し、相互作用するリソースが存在する。オーナーや獣医、革ひも、食べ物、リスなど。

dogの世界に存在するすべてのオブジェクトを呼び出すのに必要なメソッド・コールについて考えてみよう。我々のリソースのためのURLは、このようなものを見る羽目になるかもしれない。

それは滑りやすいスロープのようなもので、すぐにあなたはURLの長いリストを持つことになり、その一貫性のないパターンは、開発者があなたのAPIの使い方を学ぶことを困難にしてしまうだろう。

Use HTTP verbs to operate on the collections and elements.

我々のdogリソースについて、我々はラベルとして名詞を使う二つのベースURLを持っており、我々はそれらをHTTPの動詞を使って操作することができる。我々のHTTPの動詞は、POSTGETPUTDELETEである(我々はそれらをCRUDCreate-Read-Update-Delete)という頭字語にマッピングすることを考える)。

我々の二つのリソース(/dogsと/dogs/1234)と、四つのHTTPの動詞を使うことで、我々は開発者にとって直感的なcapability(機能?)のセットを持つことができる。ここに、我々のdogの場合について、我々の意味するものを表す図を示す。

ポイントは、APIがどのように振る舞うかを理解するために、開発者はおそらく図を必要としないということである。彼らはドキュメンテーションなしで、APIを試しながら学ぶことができる。

要約すると、次のようになる:

  • 一つのリソースにつき、二つのベースURLを使う
  • あなたのベースURLから、動詞を除きなさい
  • コレクションと要素を操作するために、HTTPの動詞を使いなさい

Plural nouns and concrete names

あなたのURLの名詞の選び方を詳しく見ていこう。

あなたのリソース名に対しては、単数名詞を選ぶべきか、それとも複数名詞を選ぶべきか?あなたは、人気のあるAPIがどちらも使っているのを見るであろう。いくつか例を見ていこう。

  • Foursquare … /checkins
  • GroupOn … /deals
  • Zappos … /Product

多くの人々がおそらくRESTfulなAPIを使って最初にすることがGETだとすれば、我々は複数名詞を使うことで、より読みやすく、かつより直感的になると考える。しかしなにより、あるリソースには単数形、あるリソースには複数形を使うといいた混在モデルになることは避けよう。一貫性を保つことで、開発者はあなたのAPIの使い方を学ぶにつれ、メソッド・コールを予測し、推測できるようになる。

Concrete names are better than abstract

純粋な抽象化を達成することが、APIのアーキテクト(設計)におけるゴールになることもある。しかしながら、抽象化がいつも開発者にとって意味があるものとは限らない。

様々なフォーム(ブログ、ビデオ、新しい記事)の中のコンテンツにアクセスするAPIの例を取り上げてみよう。

抽象化の最上位ですべてのものをモデル化したAPIは、/itemsや/assetsのようなものになるが、これらは、開発者がそのAPIで何ができるかを知るためのtangibleな(触って分かる、具体的な)図を描く機会を失ってしまう。blogs、videos、new articlesとしてリスト化されたリソースを見る方が説得力があり、役にも立つ。

抽象化のレベルは、あなたのシナリオに依る。あなたは、管理できるリソースの数を見えるようにもしたい。具体的なネーミングを目指すのと、リソースの数をキープするのは、12〜24個の間にしておこう。

要するに、直感的なAPIは単数名詞よりも複数名詞を使い、抽象的な名前より具体的な名前を使う。

Simplify associations – sweep complexity under the ‘?’

この章では、状態と属性のように、リソースとパラメータの間の関連付けを扱うときにAPIデザインで考慮すべきことについて詳しくみていこう。

Associations

リソースはほぼ常に、他のリソースとの関係を持っている。これらの関係性をWeb APIにおいて表現するシンプルな方法は何であろうか?

ここで再び、我々が名詞は良くて動詞は悪いといって我々がモデル化したAPI(dogsリソースと交流するAPI)を見てみよう。我々は二つのベースURL(/dogsと/dogs/1234)を持っていたことを思い出してほしい。

我々は、リソースとコレクションを操作するために、HTTPの動詞を使っている。我々のdogsはownersに属している。ある特定のownerに属しているすべてのdogsを取得する、もしくはそのownerに対して新たなdogを生成する場合は、それぞれGETとPOSTをする。

  • GET /owners/5678/dogs
  • POST /owners/5678/dogs

今、関係は複雑になる可能性がある。ownersはveterinarians(獣医)と関係があり、veterianariansはdogsと関係があり、dogsはfoodと関係がある、などなど。人々が5段や6段の深さを持つURLを作ってこれらを一続きにしているのを見るのは、珍しいことではない。覚えておいてほしいのは、一度あなたがあるレベルのプライマリ・キーを持てば、あなたは通常、それ以上のレベルを含める必要はない。というのは、あなたはすでに特定のオブジェクトを取得しているからである。言い換えると、あなたはURLが上記の/resource/identifier/resourceよりも深くなるような、多くのケースを必要とするべきではない。

Sweep comlexity behind the ‘?’

多くのAPIは、リソースのベースレベルを越えて入り組んだものになっている。複雑さは、リソースに関連づけられた属性と同様に、更新され、変更され、問い合わせられ得る多くの状態を含む可能性がある。

付加的な状態と属性をHTTPのクエスチョンマークの後ろに置く事で、開発者がシンプルにベースURLを使えるようにしよう。公園を走っているすべての赤い犬を取得する場合:

  • GET /dogs?color=red&state=running&location=park

要するに、あなたのAPIを直感的なものにキープするために、リソース間の関係を単純化し、パラメータとその他の複雑性については、HTTPのクエスチョンマークのラグの下に掃いて集めてしまいなさい。