「Web API: The Good Parts」を読んだ

Web API: The Good Parts

Web API: The Good Parts

仕事で API は書いてないけど API は使うのでベストプラクティスを知りたい、と思って手に取った。(「えっ!?アプリエンジニアが読んだのにサーバサイドエンジニアが読んでいないだって!? 」という煽りができるのも良い。)
電子書籍版もある ので、そっちを買って mobi を Kindle に送って読んだ。

美しい APIAPI に必要な HTTP メソッドや Status Code の考え方、エンドポイント名、フォーマット、エラー、キャッシュ、HTTPヘッダ、セキュリティなど網羅的に書かれていて、Twitter や FB などで現実に動いている API などが参考にあがってて大変良かった。
と言いつつも本を読む前からすでに理解していたことが多く、どちらかというと自分の考え方は間違っていなかったと自信がついたのが一番良かった。

HATEOAS

以前、会社のパイセンと HATEOAS どうすかね?という話をしたので自分の考えを述べておく。HATEOAS とは詳細は省くが、下記のように json のレスポンスに関連する URL をのせるものである。

   "user": {
    ....
   "links": [{
        "rel": "roles",
        "href": "http://awesomeapi.com/users/1/roles"
      }]
  }

HATEOAS の利点として、「クライアント側が取得したいデータに対しエンドポイントを知らなくて良い」「サーバ側でエンドポイント名を変更できる」があるのかなと思っている。(違ってたらツッコミ入れて欲しい)

  1. クライアント側が取得したいデータに対し URL を知らなくて良い
    • URL は知らないけどレスポンスマッピングはするから、エンドポイントの名称( roles )を元にクライアント側で API を実行する必要がある
    • サーバ側でエンドポイント名を変更されると、クライアント側のソースコードと整合性が取れずに気持ち悪い(クラス名をエンドポイントと同じにしていた場合などズレが生じる)
  2. サーバ側でエンドポイント名を変更できる
    • エンドポイント名を変えるというのはそもそもが破壊的な変更
    • 変えたいなら古いエンドポイントを生かしつつ新しいエンドポイントを作成するべきでは

エンドポイントを知らないで良いというメリットがあまりしっくりこず、私は HATEOAS 否定派である。正直に言うと、HATEOAS を使いこなせずクライアントのコードが煩雑になってしまう気がしている。

オーケストレーション

これはめっちゃ良い。クライアントのエンジニアが、複数の API などを 1 つにまとめたりレスポンス量を調節したりできるようにする仕組み。サーバは細かい API を提供して、クライアントエンジニアがそれを束ねた API を開発できるようにするような感じ。

BFF と近いものを感じていて、細かい調整などをサーバの人にお願いするのもだるいのでこう言うのあるとすごく良い。しかし、これを用意するのは結構な労力がかかるのでコスパは悪そう。
Netflix でやってるらしい。

書いて欲しかったこと

残念なことが2つあって、 JSON Scheme への言及がないことと、クライアントサイドで扱いやすい JSON 形式という視点がなかったこと。

JSON Scheme で仕様を表現するのは賛否あると思うが、そういう方法があるのは述べてて欲しかった。

また、アプリエンジニアからサーバサイドエンジニアへの JSON オブジェクトに関するお願い - Qiita という記事を前に書いたが、レスポンスオブジェクトの形式には気を配って欲しい。


以下、 wikihub 日報 の雑メモ。


読み始めた、1/3 読んだ。 これを読むことで「えっ!?サーバサイド API 実装するのに読んでないんですか?クライアントサイドの人が読んでるのに!?」という煽りができる。

今のところ知ってることが中心、 Rails 書いてたり他のサービスの API 使ってると染み付くようなことが言語化されてる感じ。

  • そのサービスのコアの価値のある部分を全て API として公開し提供しよう。
  • 設計の美しい Web API は使いやすい、変更しやすい、頑強である、恥ずかしくない
  • 仕様が決まっているものは仕様に従い、そうでないものはデファクトスタンダードに従う
    • 他の API 真似たりとかする
  • 美しい URI 設計
    • 短く入力しやすい、人間が読んで理解できる、大文字小文字が混在してない、改造しやすい、サーバ側と切り離されている、ルールが統一
  • POST は新しい情報を登録し、完全に上がいて修正は PUT, 一部修正は PATCH
  • アンダーバーかハイフンで迷ったらとりあえずハイフン

2/3 まできた。明日読み終える。 いい本なんだけど、知っていることばかりという感じ。いままでで API 開発の基礎は身についていたということだろう。

  • Chatty API (おしゃべりなAPI)
    • 1つの作業を完結するために複数回アクセスしないといけない API
  • エンベロープ
  • JSON レスポンスで直下に配列があると JavaScript としても解釈できてしまうので、オブジェクトを返した方が良い
  • JSON はアンダーバーなどではなくキャメルケースが良い
    • レールズがアンダーバーにしちゃうからアンダーバー派だわ…
  • 配列は複数形、それ以外は単数形
  • エラーが配列で変えるのは合理的、複数エラーにも対応できる
    • アプリの場合、配列でエラー返ってきても割と困るんだよなあ
  • メンテナンスは Retry-After でいつ終わるのか示そう
    • 知らなかった
  • Vary ヘッダ
  • Content-Type はちゃんと実装してテストもちゃんとしよう

読み終わった。だいたい知っている内容だったけど、 API 開発マンは絶対に読んでおいた方が良いと思う。 JSON ハイジャックやセキリュティなども述べられていて大変良い、そこらへんおろそかにしがちなので気をつけないと…。

  • 同一性生元ポリシー(Same Origin Policy)
    • 違うhostの API を実行できないやつ、むかしこれでハマった、懐かしい…。
  • クロスオリジンリソース共有(CORS: Cross-Origin ResourceSharing)
    • 異なるhostでアクセスする
  • オーケストレーション
  • HttpOnly 属性は JavaScript などを使ってもアクセスできない
    • WKWebView で Cookie 取得できないのはコレか?