「Web API: The Good Parts」読書メモ ~ その 1 ~

tl;dr

どうも私です。

お久しぶりです。

前回の投稿から 約2年半ほど間が空きました。

このブログをどう使っていこうか見切り発車だったのですが、
自身の備忘録を兼ねたアウトプットの場として使っていこうと思います。

インターネットのデブリとならないように頑張りたい所存です。

さて、今回は「Web API: The Good Parts」についてのアウトプットその 1 です。

Web API: The Good Parts

今更ながらに書籍をちゃんと読んだのですが(苦笑)、
自身の中で感覚的に理解してた API 設計の知識が整理されました。

目次

Web API: The Good Parts

1 章 : Web API とは何か？

要点

開発者が Web API を設計する機会は？

開発者が Web API を設計しなれればならない機会は様々である。

• 公開しているウェブサービスのデータや機能の API 公開
• 他のページに貼り付けるウィジェットの公開
• モダンなウェブアプリケーションの構築
• スマートフォンアプリケーションの開発
• ソーシャルゲームの開発
• 社内システム連携

上記の例のように目的は様々ですが、平たく言ってしまえば、
「異なるシステムやサービス同士を繋ぐ」際に Web API を設計する機会が発生する。

なぜ API を公開するのか？

そのサービスができることをすべて API 経由でできるようにすることで、
サービスの「価値」を自社のアプリケーションで利用可能にするだけでなく、
他社のアプリケーションでも利用可能にすることができる。

Web API がその橋渡し役となり、サービスの「価値」の拡販に繋がる。

また、優先度を下げた機能や新しい発想の機能を API 利用者が作成してくれる可能性がある。

なぜ Web API を美しく設計しなければならないのか？

「美しさ」とは以下に挙げるような完成度の高さを表す。

• よく考えられている
• わかりやすく整理されている
• 無駄がないこと

Web API を美しく設計しなければならない理由は次の通り。

• 設計の美しい Web API は使いやすい
• 設計の美しい Web API は変更しやすい
• 設計の美しい Web API は頑強である
• 設計の美しい Web API は恥ずかしくない

設計の美しい Web API は使いやすい

• 使いずらい Web API は開発期間や利用者のストレスに大きな影響が出る
• 使いずらいままではできる限り多くの人に浸透せず、 API を公開する意味が薄れる

設計の美しい Web API は変更しやすい

• サービスの進化にあわせて API にも変更が発生する
• いかに利用者に影響なく変更可能とするかが大切である
  • e.g. 不特定多数の第三者に利用されているケース
  • e.g. バージョンの異なるアプリに利用されているケース

設計の美しい Web API は頑強である

• セキュリティの問題に対してきちんと考慮して設計が必要である

設計の美しい Web API は恥ずかしくない

• センスの疑われる API を通し、サービス開発者の技術レベルも疑われる
• その結果、開発者の採用に悪い影響がでる可能性がある

「美しくする」にはどうすればいいのか？

大きく以下の 2 点が大切である。

• 仕様が決まっているものに関しては仕様に従う
• 仕様が存在していないものに関してはデファクトスタンダードに従う

その際、注意すべきがある。

1. 思考停止で人の真似をするわけではないこと
2. なぜそういう仕様、デファクトスタンダードなのかを理解すること
3. 基礎を知った上で、自身がより良いと思った仕様を試すこと

対象となる開発者の数が API 設計に与える影響とは？

Netflix 社 Daniel Jacobson 氏の記事内で、
「対象となる開発者の数」と API 設計のアプローチについて触れられている。

thenextweb.com

• LSUDs (Large set of unknown developers)
  • <和訳>
    • 未知の多数の開発者
  • <アプローチ方法>
    • 外部公開され誰でも使えるように意識した設計となる
    • 想定すべきユースケースは SSKDs よりも広く汎用的になる
    • e.g. twitter API, facebook API, github API...
• SSKDs (small set of known developers)
  • <和訳>
    • 既知の少数の開発者
  • <アプローチ方法>
    • 特定の一部の開発者にのみ使えるように意識した設計となる
    • 想定すべきユースケースは LSUDs よりも明確で専門的になる
    • REST API では対応しきれない要求が発生する可能性がある
    • e.g. 自社開発アプリ向け API, 社内システム連携向け API...

対象となる開発者が異なれば想定するユースケースも異なる。
また、何が対象の集団にとって使いやすいかを考える基準も異なる。
転じて、「美しい設計」という定義も異なってくる。

感想

第 1 章では「美しく設計する」という点について、
前提知識を共有したり読者の目線を合わせることに注力していた印象です。

個人的には LSUDs と SSKDs という概念が新鮮でした。

感覚的には両者を分けていたのですが、
名前が与えられたことにより両者の境目が明確になったと思います。

SSKDs における REST API では対応しきれない要求については、
オーケストレーションレイヤーを採用するという考え方に触れているのですが、
これが「BFF(Backends For Frontends)」へと発展していくのでしょうか？