Zenn
🐍

[Web API The Good Parts] API設計Tips - 10年の時を経て

に公開
API
Web API
O'Reilly
tech

はじめに

もはやAPI開発をしている人で読んでいない人はいないレベルの言わずと知れた名著「Web API The Good Parts」を今更ながら読んだ。
気になった部分を備忘録的にまとめておく。

原則

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

    https://api.example.com/v1/items/12345

    ざっくりこんなん。紹介されていた要素としては下記。

    • 短く入力しやすいURI
    • 人間が呼んで理解できるURI
    • 大文字小文字が混在しないURI
    • 改造しやすい(Hackableな)URI
    • ルールが統一されたURI
    • サーバ側のアーキテクチャが反映されていないURI
      例： ❌ https://xxx/yyy.php

考え方

レスポンスデータの設計

  • APIのアクセス回数がなるべく減るようにする
    • Chatty API（おしゃべり）にしない
    • 取得項目をユーザに選択してもらうのも一手
  • 不要な階層化はしない
    • フラット
      {
    "xx": "yy",
    "xx": "yy",
    "xx": "yy",
    "xx": "yy"
}
    • 階層化
      {
    "xx": "yy",
    "xx": {
        "xx": "yy"
    },
    "xx": "yy"
}
  • エラーの際にHTMLを返さない
  • セキュリティ上の理由から意図的に不正確な情報を返した方がいい場面も存在する
  • ステータスコード関連
    • 202
      • 処理は開始したが終わっていないという通知
      • 広い意味では非同期だが、プログラム的な非同期ではない
  • Chacheの期限について
    • ExpiresとCache-Controlを同時に利用した場合、新しい仕様であるCache-Controlが優先される

設計変更しやすいAPIを作るには？

  • 最もいい方法は一度公開したAPIをできるだけ変更しないこと
    • APIのバージョンでセマンティックバージョニングが多くないのは頻繁に変更することが少ないため
  • バージョンをクエリ文字列に入れずに省略して最新バージョンを使ってもらう設計は、APIの変更時にトラブルの原因となりかねない
  • バージョンを変える際の後方互換性を保たなくていい例
    • セキュリティや権限などのルールを変更した場合
    • ルールが整理されずに進化してしまったAPIをより使いやすく整理するため
  • 提供終了時の仕様
    • ステータスコード401(gone)を返し、メッセージを添える
    • 強制アップデート(ユーザ離脱を起こす要因にはなるが、エラーが出るよりはマシ)

Tips

  • 自分の情報へのエイリアス
    • self, meが使われがち
  • 性別の表し方
    • sexは生物学的な性別、genderは社会的・文化的性別

さいごに

2014年に初版・第二版が立て続けに出たあと、更新もされていないのに10年経った今でも変わらず人気であり続ける理由がわかった気がした。
API開発はレイヤが上の方の分野ではあるが、システムを作る考え方的なところはレイヤを問わず普遍的であること、それを学ぶことが将来の自分をいかに救ってくれるのかというところを痛感した。

GitHubで編集を提案

Discussion