🔔 本の下書きプレビューをシェアできるようになりました
Zenn
🐍

精読「Web API: The Good Parts」(1)

2025/01/21に公開
API
Web API
tech


Web API: The Good Parts
Web APIの設計と開発における「本当に大切な部分」を凝縮した一冊。シンプルで使いやすいAPIを実現するためのベストプラクティスと、その背景にある思想を解説します。RESTの基本から、セキュリティ、パフォーマンス、エラーハンドリング、バージョニングまで、実務に役立つ知識が詰まっています。

この書籍では、実例を通じて良いAPI設計の判断基準を学べるだけでなく、なぜそのアプローチが優れているのかを深く理解できます。さらに、「これだけは避けたい」という悪い例も取り上げられており、実践的なスキルが身につきます。

開発者、アーキテクト、プロダクトマネージャーにとって、Web API設計の基礎と応用を学ぶ最良のガイドとなる一冊です。

関連記事

https://zenn.dev/joaan/articles/b878d661e6a97c
https://zenn.dev/joaan/articles/95ec2e3d27d9a3
https://zenn.dev/joaan/articles/94c50168f7a009

Web APIとは何か

本書の目的

Web APIを効果的に設計・運用する方法を探り、よくある課題や誤った設計を避けるためのガイドを提供する。

Web APIの定義

HTTPプロトコルを使用し、ネットワーク越しに呼び出されるAPIを指す。URIをエンドポイントとし、機械的なデータ取得や操作を目的としている。例としてTwitter APIが挙げられる。

特長と利用例

  • ブラウザで人が直接アクセスするためではなく、プログラムがデータを取得・活用するための仕組み。
  • JSON形式など、加工や再利用が容易なデータ形式が多い。
  • 主にJavaScriptやクライアントアプリから利用される。

ターゲットとするAPI

シンプルな形式（JSONやXMLをHTTPでやり取りするもの）を主に扱う。一方で、SOAPやXML-RPCのような厳密な仕様も存在するが、そうしたルールに縛られない実例が多く、課題も顕著。

REST APIについて

RESTには厳密な定義があり、本書では誤解を避けるため「広義のREST」をRESTと呼ばない。ただし、RESTの思想には学ぶべき点が多く、本書でも基本を取り上げている。

Web APIの重要性

Web APIの役割と価値

Web APIは企業やサービスの価値を大きく左右する重要な要素となり、APIを公開することで新たな価値を生み出すエコシステムが形成されている。成功例としてAmazonのProduct Advertising APIやTwitterのAPIが挙げられ、それらは開発者による付加価値の創出や収益の拡大を促した。

APIを前提としたサービスの登場

近年、TwilioやPocketなどのようにAPIを基盤としたサービスが増え、機能を単独で提供する形態が主流となっています。また、GitHubなどは他サービスとAPI連携を通じて共存共栄を実現している。

スマートフォン普及とAPIの役割

モバイルアプリの増加に伴い、APIがアプリとサーバをつなぐ重要な役割を果たしている。

APIエコノミーの台頭

APIの普及により、MasheryやApigeeのようなAPI管理ビジネスが成長。APIが新たな価値創出の基盤となる「APIエコノミー」が注目されている。

さまざまなAPIのパターン

公開しているウェブサービスのデータや機能のAPI公開

外部にサービスを提供するために、データや機能をAPIとして公開する例。
有名な事例としてAmazonやTwitterのAPIが挙げられる。API公開時には、使いやすい設計や詳細なドキュメントの提供が必要であり、バージョン管理やユーザー登録、アクセス制限の考慮も重要。また、モバイル向けのSDK提供も検討する場合がある。

他のページに貼り付けるウィジェットの公開

Facebookの「いいね」ボタンやAmazonの商品ウィジェットなど、他のページに貼り付ける機能を提供するケース。
ウィジェットはバックエンドAPIを利用して情報を送受信する。クロスドメイン対応や不正アクセスへの対策が必要で、クライアント側コードが見られるリスクがあるため、セキュリティの強化が求められる。

モダンなウェブアプリケーションの構築

ページ遷移を伴わないモダンなウェブアプリケーションでは、AJAXを用いたAPI連携が主流。
データサイズを抑え、ユーザー体験を向上させるためにAPIを設計する必要がある。ウィジェット同様、クライアント側のコードが公開されるリスクがあるため、不正アクセスを防ぐ対策が求められる。

スマートフォンアプリケーションの開発

スマートフォンアプリケーションのバックエンドとしてAPIを設計するケース。
ブラウザに比べると不正アクセスの難易度は高いが、ネットワークを介したデータ取得が可能であるため、セキュリティ対策は依然として重要。また、アプリが古いAPIに依存する場合があるため、バージョン管理や移行戦略が必要。

ソーシャルゲームの開発

ソーシャルゲームでは、サーバと通信を行うAPIが必要になる。
ゲーム内のチートや不正アクセスが多発しやすく、セキュリティ強化が不可欠。特に、アイテム売買や課金要素が絡む場合、セキュリティ上のリスクが増すため、十分な対策が求められる。

社内システムの連携

社内システム間での連携にAPIを利用するケース。
各システムを疎結合にすることで、変更時の影響を最小限に抑えられる。APIは汎用性が高く、多くの開発者が扱いやすいため、導入のメリットが大きい。

何をAPIで公開すべきか

API公開のポイント

公開すべき内容

サービスのコア価値をAPI経由で利用可能にする。例：ECサイトなら商品の検索・購入機能。

リスクと対策

  • データ盗用の懸念は杞憂。公開しない場合でもスクレイピングなどで取得される可能性がある。
  • APIにはレートリミットや利用規約を設定し、不正利用を防止。

メリット

  • 他者がAPIを活用して新機能を開発することで、サービスの価値が向上する。
  • サービスエコシステムが拡大し、自社サービスの普及が加速。

結論

API公開は、現代の「間接販売」モデルでサービスを拡販するための重要な戦略。

Web APIを美しく設計する重要性

Web APIを美しく設計する理由は以下の通り。

使いやすさ

美しいAPIは簡単に利用できるため、開発者のストレスを減らし、開発期間を短縮できる。APIの使い勝手が悪ければ、公開する意味が薄れてしまう。

変更しやすさ

サービスやシステムは進化するため、APIも変化が必要になる。美しいAPI設計では、仕様変更が利用者に影響を与えず、既存のサービスに障害を引き起こさないよう配慮される。

頑強さ

APIはインターネットを通じて公開され、セキュリティの問題がつきまとう。美しいAPIはこれらの問題にもしっかり対処し、安全性が確保される。

恥ずかしくない

開発者は他の開発者のコードやAPI設計を見て評価する。美しくないAPI設計は、そのサービスを開発している企業の技術レベルを疑わせることになり、優れた開発者を引き付けることができなくなる可能性がある。

Web APIを美しくするには

Web APIを設計する際には、公開する内容やアクセス先、通信方法、レスポンスデータの形式、セキュリティやアクセス制限について考慮する必要がある。本書では、良いAPI設計を実現するためのステップを順番に解説する。

本書の根幹となる原則は、以下の2つである：

  1. 仕様が決まっているものには従う
  2. 仕様がない場合はデファクトスタンダードに従う

これらは単なる模倣ではなく、これまで多くの人々が検討して決定したものに従うことが理にかなっているということを意味している。デファクトスタンダードも、既存のAPI設計を参考にして最適化された選択である。

また、既存の仕様に従うことで、他の開発者がAPIを簡単に理解でき、既存のクライアントライブラリを活用できるため、開発の手間やストレスを減らすことができる。

もちろん、既存の仕様に満足できず、新しい仕様を提案できる自信があるなら、それも素晴らしい進化である。しかし、重要なのは、現行のスタンダードを理解し、その上で新しいアイデアを考えることである。

RESTとWeb API

本書では「REST」という言葉を使わずにAPI設計を解説する。一般的な「REST API」の認識はHTTPでXMLやJSONを返すAPIだが、元々のREST定義と本書の設計ルールが必ずしも一致しないため。Fielding氏の定義に従うと、動詞をURIに使うことは避けるべきだが、実際の設計では「search」などの語を使う方が分かりやすい場合もある。本書は現実的で美しいAPI設計を目指する。

対象となる開発者の数とAPIの設計思想

Netflixのエンジニアリングディレクター、Daniel Jacobson氏は、API設計において「LSUDs（large set of unknown developers）」と「SSKDs（small set of known developers）」という概念を紹介した。LSUDs向けのAPIは広く汎用的に設計され、誰でも使えるようにする必要がある。一方、SSKDs向けのAPIは特定の開発者に向けて、より便利で使いやすいものを目指すべきだ。これからのAPI設計では、この2つのターゲットに応じたアプローチが重要であり、LSUDsとSSKDsの違いを理解することが鍵となる。また、SSKDs向けにリソースベースの設計だけでは不十分で、オーケストレーション層を導入する必要があると述べている。

まとめ

  • [Good] Web APIを公開していないなら、すぐにその公開を検討する
  • [Good] Web APIを美しく設計する
  • [Good] RESTという言葉にこだわりすぎない

エンドポイントの設計とリクエストの形式

本章では具体的なAPI設計のルールや方法について解説する。Web APIを公開する際には、まず何を公開するか、どのような形で公開するかを決める必要がある。そのためには、公開する機能の決定と、それを実現するエンドポイントの設計方法を考えることが重要だ。

APIとして公開する機能を設計する

SNSサービスを公開するためのAPI設計について考えるとき、まず何をAPIとして公開するかを決める必要がある。簡単なSNSサービスの場合、ユーザー登録や友達管理、メッセージ機能などが考えられる。最初はこれらの機能をAPIとして提供することになる。

基本的に、データベースのテーブルを直接操作するようなシンプルな設計も可能だが、それでは使いやすいAPIとは言えない。APIは、ユーザーがどのように使うかを想定し、そのユースケースに沿った設計が求められる。内部のデータ構造をそのまま公開することは、セキュリティの観点でも問題があるため、APIはより高いレベルの機能を提供すべきだ。

次に、モバイルアプリケーション向けのAPIを設計する際は、画面遷移を考え、それに対応するAPI機能を列挙していく。例えば、ユーザー登録、ログイン、自分の情報の取得・更新、友達の追加・削除、メッセージの投稿・編集・削除などが必要となる。

これらの機能を整理して、重複を避けるために統合できる部分は統一することが大切だ。

API エンドポイントの考え方

エンドポイントの設計はAPIの使いやすさ、メンテナンス性、開発者の生産性に大きな影響を与えるため、慎重に行う必要がある。

エンドポイントの基本的な設計

APIのエンドポイントは、その機能を示すURI（Uniform Resource Identifier）。エンドポイントを設計する際は、単に機能を実装するだけでなく、以下の設計原則を守ることで、APIを使いやすく、効率的に利用できるようになる。

覚えやすく、どんな機能を持つURIなのかがひと目でわかる

APIのURIは、開発者が見てすぐに何をするためのエンドポイントなのかが理解できるように設計することが重要。これにより、間違ったエンドポイントを呼び出したり、APIの機能を誤解して使うことを防げる。例えば、以下のようなエンドポイント設計がわかりやすいとされている。

  • 良い例: https://api.example.com/v1/products/12345
    • productsが製品に関連するデータを取得するエンドポイントであることがわかる。
  • 悪い例: https://api.example.com/v1/getdata?id=12345
    • 「getdata」という名前だけでは何を取得するのか不明確。

短く入力しやすいURI

URIはできるだけ短く、簡潔に保つべき。これにより開発者がアクセスする際に手間がかからず、間違えにくくなる。無駄な情報を省き、最も重要なリソースを示す部分だけを残す。

  • 良い例: https://api.example.com/products/12345
    • 「products/12345」の部分が製品情報を指すことが明確。
  • 悪い例: https://api.example.com/service/api/getProductInformation/product/12345
    • 余分な「service」「api」などの単語が含まれており、理解が遅くなる。

人間が読んで理解できるURI

エンドポイントは人間が見ても、その機能や目的が直感的にわかるように設計する必要がある。意味不明な略語や文字列の使用を避け、一般的に理解される単語を使うことが大切。

  • 良い例: https://api.example.com/products/12345
    • 「products」は製品情報を表す英単語で、誰が見ても理解しやすい。
  • 悪い例: https://api.example.com/sv/u/12345
    • 「sv」や「u」といった省略語は、何を意味するのか不明確で、開発者が理解するまでに時間がかかる。

省略形について
省略形は使うべきではない。例えば「products」を「prod」と省略するのは混乱を招きやすい。また、英語の略語でも、特定の業界や文化でしか理解されないものがあるため、一般的な英単語を使用することが推奨される。

大文字小文字の統一

APIのエンドポイントでは、大文字と小文字が混在しないように統一した命名規則を使うべき。通常、URIはすべて小文字を使うことがベストプラクティスとされている。

  • 良い例: https://api.example.com/products/12345
    • すべて小文字で書かれており、統一感がある。
  • 悪い例: https://api.example.com/Products/12345
    • 「Products」のように大文字を使うと、APIリクエスト時にケースミスが発生する可能性が高くなる。

ルールの統一

エンドポイントの設計には、統一されたルールが必要。例えば、リソースのアクセス方法に関するルール（名詞か動詞か）、リソースIDの取り扱い、クエリパラメータの位置などを定め、一貫性を保つことが重要。

  • 良い例: リソースの作成にはPOST /products、更新にはPUT /products/{id}、削除にはDELETE /products/{id}など、HTTPメソッドに応じた一貫した設計を行う。
  • 悪い例: 作成はPOST /create-product、削除はDELETE /delete-productなど、リソース名に動詞を入れると混乱を招く可能性がある。

改造しやすいURI（HackableなURI）

APIのURIは、将来的な拡張を容易にするためにも改造しやすい構造にしておくべき。例えば、リソースを追加する際に既存のURIに新しいパスを追加するだけで対応できるように設計することが望ましい。

  • 良い例: https://api.example.com/productsに新しいリソース（例えばreviews）を追加したい場合、https://api.example.com/products/{id}/reviewsという形式で追加できる。
  • 悪い例: https://api.example.com/product-reviewsのように、個別のエンドポイントを新たに作ると、拡張が難しくなる。

サーバ側のアーキテクチャが反映されていないURI

URIにはサーバ側の実装やアーキテクチャを反映させるべきではない。URIはあくまでリソース指向であり、どのようにそのリソースが内部で管理されているかはURIに反映させないほうがよい。

  • 良い例: https://api.example.com/products/12345
  • 悪い例: https://api.example.com/database/products/12345
    • 「database」などの内部実装をURIに含めるのは、将来の変更や拡張を難しくする可能性がある。

まとめ

APIのエンドポイント設計は、シンプルで直感的であるべき。良い設計は、APIを利用する開発者の生産性を向上させ、エラーを減らし、メンテナンス性を高めることに繋がる。URI設計の際には、短く、わかりやすく、統一感を持たせることを意識しよう。

HTTPメソッドとエンドポイント

APIエンドポイントとHTTPメソッドの関係について。主にHTTPメソッド（GET、POST、PUT、DELETE、PATCHなど）の役割や使い方について触れている。

  1. HTTPメソッドの概要:
    HTTPメソッドは、APIにアクセスする際に指定するもので、例えば、GETはリソースの取得、POSTは新しいリソースの登録、PUTはリソースの更新、DELETEはリソースの削除、PATCHはリソースの一部変更を行う。

  2. GETメソッド:
    GETはリソースを取得するために使われ、サーバ側のリソースが変更されることは基本的にない。

  3. POSTメソッド:
    POSTは新しいリソースを作成するために使用され、フォームでデータを送信する際によく使われる。リソースの更新や削除は本来PUTやDELETEを使うべき。

  4. PUTメソッド:
    PUTは既存のリソースを完全に上書きするために使われる。PATCHメソッドは一部のデータだけを変更するために使用される。

  5. DELETEメソッド:
    DELETEは指定したリソースを削除するために使う。

  6. PATCHメソッド:
    PATCHはリソースの一部を変更するために使われ、PUTメソッドよりも効率的に部分更新が行える。

  7. X-HTTP-Method-Override ヘッダ:
    もしPUTやDELETEなどのメソッドが使えない環境でも、POSTメソッドを使ってサーバに実際に使いたいメソッドを指定するための方法。

これらを組み合わせてAPIを設計すると、リソースとその操作方法を分けて明確にすることができ、メソッドごとの役割をしっかりと管理できるようになる。

APIのエンドポイント設計

ここまでの内容を基に、SNSアプリケーションのAPI設計を進める上での重要なポイントがいくつかありる。エンドポイント設計に関しては、基本的にリソースに対してHTTPメソッドをどのように適用するかを考えることが中心。SNSのようなアプリケーションでは、ユーザー情報や近況、友達関係といったリソースを操作することが頻繁に行われる。

エンドポイント設計の要点

  1. 複数形の名詞を利用
    リソースの集合を表すエンドポイントには複数形の名詞を使う。例えば、ユーザー情報に関するエンドポイントは/users、友達に関するものは/friendsのようにする。これにより、集合のリソースにアクセスする意味を明確にできる。

  2. リソースの階層構造
    個々のリソースにアクセスするためには、リソースのIDをパスに含める。例えば、特定のユーザーの情報を取得する場合、/users/:idのように、ユーザーIDをプレースホルダで示す。これにより、リソースに対する明確な操作を行うことができる。

  3. HTTPメソッドの適切な使用

    • GET: リソースの取得
    • POST: リソースの作成
    • PUT/PATCH: リソースの更新
    • DELETE: リソースの削除

これらのメソッドを、リソースに対する適切な操作として使い分ける。例えば、ユーザー情報の取得にはGET /users/:idを使い、ユーザーの情報更新にはPUT /users/:idを使う。

  1. クエリパラメータの活用
    ユーザーの検索やフィルタリングを行う場合、クエリパラメータを使用することで、リストの絞り込みができる。例えば、GET /users?name=Johnのように、nameでユーザーを絞り込むことができる。

  2. 直感的なURI設計
    URIはシンプルで直感的に理解できる形に保つことが重要。例えば、/users/:id/friendsという形にすることで、「特定のユーザーの友達」にアクセスしていることが一目でわかる。

  3. 権限管理
    ユーザーがアクセスできるリソースを適切に制限する必要がある。例えば、ログインしたユーザーは自分の情報を更新できるが、他のユーザーの情報を変更することはできない。

具体例：

  1. ユーザー情報

    • ユーザー一覧取得: GET /v1/users
    • ユーザー新規登録: POST /v1/users
    • ユーザー情報取得: GET /v1/users/:id
    • ユーザー情報更新: PUT /v1/users/:id
    • ユーザー情報削除: DELETE /v1/users/:id

  2. 友達情報

    • 友達一覧取得: GET /v1/users/:id/friends
    • 友達追加: POST /v1/users/:id/friends
    • 友達削除: DELETE /v1/users/:id/friends/:friend_id

  3. 近況情報

    • 近況投稿: POST /v1/updates
    • 近況編集: PUT /v1/updates/:id
    • 近況削除: DELETE /v1/updates/:id
    • ユーザーの近況取得: GET /v1/users/:id/updates
    • 友達の近況一覧取得: GET /v1/users/:id/friends/updates

これらの設計を基に、各リソースにアクセスするためのエンドポイントをしっかり定義し、利用者にとって使いやすいAPIを提供することが重要。

検索とクエリパラメータの設計

この内容は、RESTful APIにおける検索とクエリパラメータ設計に関する非常に詳細な解説。

ページネーション（Pagination）の設計

  • 必要性: 一度に大量のデータを取得するとパフォーマンスに影響が出るため、データの分割取得が必要。
  • 方法:
    • 相対位置指定: limit と offset、または per_page と page。
      • 例:
        • limit=50&offset=100 (100件目から50件取得)
        • per_page=50&page=3 (3ページ目の50件を取得)
      • offset は0基準、page は1基準が一般的。
    • 絶対位置指定:
      • 例: max_id (ID指定)やpublishedBefore (日時指定)。
      • 問題点を回避するために有効（パフォーマンスやデータ整合性）。

相対位置指定の問題

  • パフォーマンス問題:
    • 大量データの場合、offset での先頭からのカウントがボトルネックになる。
  • データ整合性問題:
    • データ更新が頻繁に行われると、取得したデータが最新と一致しない場合がある。

絞り込み（検索）用パラメータ

  • 複数項目での絞り込み:
    • 例: first-name や last-name など、特定フィールドで絞り込む。
      • http://api.example.com/v1/users?first-name=Ken
  • 単一フィールド（qパラメータ）:
    • 汎用的な検索に使われ、部分一致にも対応。
      • http://api.example.com/v1/users?q=Ken

絶対位置指定のメリット

  • 効率的なデータ取得:
    • max_id や publishedBefore で効率的に次データを取得可能。
  • データの一貫性:
    • 更新頻度が高いデータでも、不整合を回避。

特に、相対位置指定と絶対位置指定の使い分けが重要なポイント。

ログインとOAuth2.0

この内容はOAuth 2.0における認証とトークン管理について、主要なポイントを整理する。

OAuth 2.0の概要

  • 目的: 第三者サービスがユーザーのデータにアクセスできるようにする仕組み。
  • 特徴:
    • ユーザーはサービスのパスワードを直接提供せずに認証が可能。
    • アクセストークンを利用して認可された範囲でデータへアクセス。

      OAuthの概要とそれを取り巻く環境より

主な要素

  1. アクセストークン: サービスにアクセスするための鍵。ユーザー情報や権限を含む。
  2. トークン発行フロー (Grant Type):
    • Authorization Code: サーバサイドアプリケーション向け。
    • Implicit: クライアントサイドアプリケーション向け。
    • Resource Owner Password Credentials: 自社アプリケーションでの直接ログイン。
    • Client Credentials: ユーザーを特定せずクライアントのみ認証。

リクエスト・レスポンス例

リクエスト

POST /v1/oauth2/token HTTP/1.1
Host: api.example.com
Authorization: Basic <Base64(Client ID:Client Secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=<ユーザー名>&password=<パスワード>&scope=api

レスポンス

{
  "access_token": "b77yz37w7kzy8v5fuga6zz93",
  "token_type": "bearer",
  "expires_in": 2629743,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

トークンの使用方法

  1. ヘッダーに指定:
    Authorization: Bearer <アクセストークン>
  2. ボディに指定:
    access_token=<アクセストークン>
  3. URLクエリに指定:
    GET /v1/users?access_token=<アクセストークン>

トークンの有効期限と更新

  • 有効期限: expires_inに指定された秒数で決定。
  • リフレッシュトークン: アクセストークンの期限が切れた場合、新たなトークンを取得するために利用。

OAuthを利用するメリット

  1. 標準化: 広く利用されているため、開発や運用のハードルが低い。
  2. セキュリティ: パスワードを直接渡さず認証可能。
  3. 柔軟性: 権限をスコープで制御できる。

OAuth利用時の注意

  • アクセストークンの管理: 有効期限やアクセス範囲を適切に設定する。
  • スコープの設計: 必要な権限のみを付与することでセキュリティを確保。
  • クライアント認証: Client IDとClient Secretを活用してアプリケーションを特定する。

ホスト名とエンドポイントの共通部分

このセクションでは、API設計におけるエンドポイントの共通部分とホスト名の選定について、ポイントを簡潔にまとめると次のようになる。

  1. エンドポイントの共通部分

  2. ホスト名のパターン

    • 多くのサービスが「api.example.com」のように、ホスト名にapiを含める形式を採用。
    • apiをホスト名に含めることで、DNSレベルで管理がしやすくなり、URIも簡潔になる。
    • 例外として、Yammerのようにホスト名にapiを含めず、パスの中に入れているケースもあるが、一般的ではない。

  3. バージョン管理

    • パスにv1やv2といったバージョン番号を含めるのが主流。
    • APIのバージョン管理については後述する章で詳細に議論。

  4. その他のパターン

    • 特定の用語（例: openapiやapi-public）を含めることで、APIの性質（オープン／クローズドなど）を明示するケースもある。
    • 複数サービスを提供する企業では、googleapis.comのように専用のホストを使う例も。

  5. 用語の選択

    • apiとwebserviceの選択について議論。
      • apiはプログラムがアクセスするものとしてわかりやすい。
      • webserviceは人間も対象にしたサービスを意味する場合があるため、APIの文脈ではやや曖昧になる。
    • 結論として、apiを使用する方が適切であると推奨。

  6. 楽天の例

    • 「app」「services」「api」と似た単語が並ぶ構成は冗長である。
    • 外部利用者から見てシンプルな構造にすることが望ましい。

APIを提供する際には、ホスト名として「api.example.com」を使うのが最も一般的かつ適切な設計である。これは簡潔でわかりやすく、管理もしやすいという利点があるため。

SSKDsとAPIデザイン

ここまでで、主に一般公開型API（LSUDs: Large Scale Undifferentiated Users）向けの設計について議論してきたが、SSKDs（Small Scale Known Developers）向けのAPI設計には異なる視点が求められる。SSKDs向けAPIでは、汎用性や美しい設計よりも、エンドユーザーにとっての ユーザー体験 を優先することが重要。

SSKDs向けAPI設計の特性

  1. エンドユーザーの体験を重視

    • たとえば、Eコマースアプリのホーム画面では、新着商品、人気商品、ユーザー情報、購入履歴に基づくおすすめ商品、カート情報など、さまざまな情報が必要。
    • 一般的なAPI設計では、これらの情報がそれぞれ個別のエンドポイントとして提供されるかもしれない。しかし、それでは1画面を表示するために複数回のAPIコールが必要となり、効率が悪くなる。

  2. 1スクリーン1APIコール

    • 「1スクリーン1APIコール」 の原則に従い、特定の画面に必要なデータをすべて含む専用のAPIを設計する。これにより、画面の読み込み時間を短縮し、スムーズな体験を提供できる。
    • データ保存時も 「1セーブ1APIコール」 の原則を適用し、一度のリクエストで整合性のあるデータ保存を実現する。

  3. 利便性と整合性の確保

    • 複数回のAPIアクセスは速度の低下だけでなく、データの不整合や不完全な表示を招くリスクがある。
    • ユーザーにストレスを与えないよう、APIの設計にはクライアントアプリのユースケースを詳細に反映させる。

ユースケースに基づく設計

SSKDs向けのAPIは、汎用性よりも 特定のユースケース に適した設計が求められる。クライアントアプリケーションごとに異なるニーズがある場合には、画面や操作単位で専用のAPIを提供するのが効果的。

課題と解決策

  1. ユースケースの多様化

    • 複数のクライアントアプリケーションにAPIを提供する場合、エンドポイントの数が増え、管理が複雑になる。
    • 解決策として、シンプルなAPIを提供する層（Core API）とクライアント間に オーケストレーション層 を挟むアプローチがある。この層がクライアントの多様な要求を取りまとめ、効率的に処理を行う。

  2. 汎用性と特化設計のバランス

    • 完全に特化型のAPI設計は便利ですが、汎用的な要素を適度に取り入れることで、将来的な拡張性を確保することも重要。

SSKDs向けAPIの設計では、単に「技術的に正しい」設計を目指すのではなく、エンドユーザーに最適な体験を提供する ことを第一のゴールとして考える必要がある。このアプローチを意識することで、APIの価値を最大化できる。

HATEOASとREST LEVEL3 API

REST APIの設計には複数のレベルがあり、Martin Fowler氏の分類に基づいて、通常はREST LEVEL2（基本的なHTTP動詞とリソースの使用）が一般的。一方、REST LEVEL3はHATEOAS（Hypermedia As The Engine Of Application State）を導入することで、クライアントが次にどの操作を行うかをリンクで示す設計。

HATEOASでは、APIのレスポンスに次に実行すべき操作やデータ取得のURIが含まれ、クライアントは事前にエンドポイントを知らなくても、リンクを辿ることでAPI機能にアクセスできる。例えば、SNSの友達一覧のデータには、各友達の詳細情報へのリンクが含まれる。

REST LEVEL3 APIのメリット

  • 柔軟なURI管理：URIを変更してもクライアント側の修正が不要になるため、保守性が向上する。
  • URIの隠蔽：セキュリティ向上のため、アクセス先のURIを人間が理解しにくくできる。

REST LEVEL3 APIの採用

REST LEVEL3は特定のクライアント向けAPI（SSKDs）に適しており、オープンAPI（LSUDs）にはまだ時期尚早かもしれない。しかし、将来的にHALなどの規格が普及すれば、クライアントとサーバの双方が柔軟に対応できる利点がある。

まとめ

本章では、APIのエンドポイント設計について、URIやHTTPメソッドの組み合わせを基にした良い設計の方法を見てきた。APIエンドポイントは、ウェブページと同様にURI設計の考え方を適用できる一方で、API特有のルールやデファクトスタンダードもある。良いAPI設計には、URIがリソースを表し、HTTPメソッドを用いて処理対象と内容を表現することが基本とされている。

また、実際のAPI設計を比較することで、優れた設計を見極めることが重要です。ProgrammableWebなどのAPIディレクトリサイトを活用して、多くのAPIの設計を調べることをおすすめする。

  • [Good] 覚えやすく、どんな機能を持つかがひと目でわかるエンドポイントにする
  • [Good] 適切なHTTPメソッドを利用する
  • [Good] 適切な英単語を利用し、単数形、複数形にも注意する
  • [Good] 認証にはOAuth 2.0を使う

参考

Discussion

ログインするとコメントできます