APIの設計手順

API設計時の悩み

いざ「APIを作ろう」となった時に、いろいろ迷う人も多いのではないでしょうか。

何をどれだけ作るべきか迷う
誰と一緒に意思決定すべきか迷う
認証やセキュリティをどうすればよいかわからない
どのようなインフラを選べば良いか分からない
良い書籍がない（良著も古いものが多い）
運用後をどこまで想定すればよいかわからない
英語の情報が多い

上記は意思決定について主なものをあげていますが、選択するアーキテクチャ（SOAPもしくはrestfulにするか）、プログラミング言語の選択、スケーラビリティ、オープンにするなら宣伝方法など考えなくてはいけない問題が数多くあります。

そもそもAPIにはウェブ経由のAPIだけでなく、WindowsやJava、HTML5にもAPIは存在しますし、APIという言葉の広義さ故に混乱することもあるでしょう。

さらには最新技術が絶えず変化する中で、なるべく効率的に拡張性のある開発を目指さなければいけません。これななかなか骨が折れます。

APIの設計は「ユーザー」が決める

実はAPI設計に関わる諸問題を考える前に、最も考えるべきことがあります。

それは あなたのAPIは誰が使う想定なのか？ ということです。

限定されたユーザーのみに公開するのか、それともイントラネットを通じて特定の技術者に提供するのか。VPN経由で協力会社の人にだけアカウントを発行して使ってもらいたいということもあるかもしれません。

当然、そのユーザーの想定によってAPIの市場規模がきまり、また採用するアーキテクチャーも絞り込まれていくでしょう。

結局APIはユーザーが使うものなので、こちらが考えただけでは使ってもらえないことも多くなります。

このことに気づくかどうかで、その後の開発効率は大きくかわります。

APIを開発するときに多くの諸問題で悩むのは、この「設計ポリシーはユーザーで決まる」というルールに気づいていないからです。つまり最初に決めるべきは利用者＝ユーザーです。

APIは一般的な商品開発に似ている

ユーザーを想定して作るというのは、何も珍しいことではありません。マーケティング活動 として一般的な商品開発の現場で行われています。

例えば飲料水など一般的な商品開発では、市場規模の想定や、アンケートなどを用いたユーザーリサーチ、またユーザーの本音を探るインサイトなどが、当たり前のマーケティング活動として行われています。

同様に、API開発についても顧客をより深く知り、その上でシステム上の制約なども含めて適切な解を出すことがAPI設計者に求められることになります。

ただしAPI開発において既存の商品開発やシステム開発と大きく違うのが、永久のβ版という考え方です。

わかりやすいのはGoogleのGmailなどのサービスでしょう。運営を続けながら、よりユーザーと自社のビジネスにとってメリットがあるように変化し、PDCAサイクルが繰り返されます。

同様に、APIも終わりがない開発になることが多いです。市場に出したのち、ユーザーから継続してバージョンアップすることが求められることが多いためです。

永久のβ版という呪縛

このような状況はAPI企画・開発者にとって頭の痛い話です。

なぜなら、システム開発を低コストで効率的に進めるには、最初にシステムの全体像を想定しておきたいところです。

しかし永久のβ版となると、初期にそのような網羅的な想定は不可能であり、それならいち早く市場に出した方がよいかもしれません。

このあたりの結論は、開発手法としてウォーターフォールとアジャイルの比較や、リーンスタートアップやマイクロサービスといった開発思考法の登場で、既に多く議論されていますので、本サイトの範疇としては扱いません。

一点、PeterThielの著書ZeroToOneという中の250の企業を調査した結果を紹介するならば「リーンスタートアップのような仮説検証を繰り返す手法は一般的に有効である。しかし、AIのようなより研究に近い0から1を生み出すような事業においては、それよりも強い戦略を持つ方が重要である」ということです。

つまり目的によって手段は変化します。

そこで本サイトでは、どのような開発手段をとったとしても「顧客が気に入るAPIを制作し、β版として改良を続けることが重要である」という普遍的な原則にたち、API設計の手順の一例を示します。

API設計の手順

ユーザーの想定と永久のβ版を想定しておくことがAPI設計のポイントであることがわかった上で、適切なAPI設計の手順について考えてみましょう。

適切なAPI設計には、顧客と市場を理解した上で企画をたて、その後API設計を始め、最後に計画するという普遍的な手順があります。少し事業計画に似ているかもしれません。

※なお、ここでの設計ではいわゆるWebサービスAPI（HTTPを介したAPI）のみ対象にしています。

企画・準備

作成するAPIがユーザーに提供する価値・ビジョンを明確にする

トレンドを知っておく

他が真似できない資産（所有するデータやサービス）の棚卸しをする

市場調査・戦略

自社の強みとビジネス性を分析する（SWOT分析など）

APIを利用するユーザーを詳しく知る（もしくは想定する）

利用ユーザー数を想定する

将来を予測する

どのような情報をどのような頻度で交換するAPIを作るか想定する

API設計（開発・公開・運用）

WebサービスAPIの設計

API利用者管理とセキュリティについて検討する

適切なAPIスタイルについて検討する

RPC型のAPI
メッセージ送受信型のAPI（SOAP API）
自社リソースへのアクセス手段を用意するAPI（REST API)

将来の発展・互換性・ライフサイクルを検討する

API定義書（ユーザーマニュアル）や開発者ポータルについて検討する

パフォーマンスとインフラに関して検討する

フレームワークや運用後の管理手法について検討する

体制について検討する

必要なサービス品質レベルについて考える

実行計画: チーム構成と構築計画（上司や協力先など）; 初期マーケティングと計測について検討する; 工数とスケジュールを見積もる; ロードマップを作る

企画の重要性と注意点

オープンにするWebAPIの設計において、特にビジネス、つまり商品として販売できるようなAPIを開発しようとするならば、企画を先行させ、それに技術的な裏付けをする方が理にかなっているでしょう。

ただ一般商品とは違う注意点として、一般の商品であれば金銭のやりとりは発生させやすいですが、APIにおいてはデータのやりとりであり、基本的に「データは無料」の文化が定着しています。

この無料を中心とする文化において商品として成立するAPIを作るには マーケティング要素をしっかり考慮する 必要があります。

とはいえ既存のシステムで外販を経験したことがある人は希でしょうし、そもそもマーケティングの経験があるエンジニアも少ないことでしょう。このような事情があるので、本サイト「APIbank」では、特に企画方法について、連載の中で回を重ねながらご説明していきたいと思っています。

技術的な設計手法については、企画内容や今後の技術の発展に伴って変化することも考えられるので、連載というよりは、コラムのような形で、都度APIキュレーターにより適切なコンテンツをアップしていきたいと思っています。