既存システムにWebAPIを設計、実装した時の反省点

Posted at 2015-12-06

日付が変わってしまいましたが、Enterprise APIs Advent Calendar 2015の6日目です。

既存システムにWebAPIを実装した時に後から「ああしておけばよかった」「こうしておけばよかった」と思ったことをつらつら書いてみたいと思います。

前提

前提にも記載した通り、既存画面の機能に対してWebAPIの口を作る方針で対応していたのですが、GETで取得するようなものは比較的簡単に設計を進めることができました。

しかし、登録系の操作に落とし穴がありました。

例えばレコード登録機能のリソース設計について、既存機能ではCSVファイルで一括レコード登録が出来るので以下のように設計しました。

POST /api/v1/hogehoge/records
※マルチフォームでCSV形式データを送信

後日、同じレコード登録で1件登録とZIPされた複数ファイルでの登録機能もあることに気がつきました。

この時、POST /recordsはもう使ってしまったので、素直なリソースを設定できなくなり、POST /records/input、POST /*/records/zip という微妙なリソースを割り当てることになってしまいました。

といった感じの流れにしておけば、複数の方法での登録処理に対応する時も整合性のある設計にできたんじゃないかと後悔しています。

教訓：自分が渡されて困る形式にしてはいけない

デモ環境用意して、そこにリクエスト投げて動作を見れるような（Swaggerのような）ドキュメントを用意するべきでした。
社内政治とか、工数削減圧力とか、社内の採用実績、（フレームワーク使う場合）知名度などでExcel/Wordに流れることはありがち……。

ネット上のサンプル実装とか見て回って以下のような感じで返すようにしました。　

{
  'link' : [
    {
      'url' : 'https://hoge.com/api/v1/records/1',
      'rel' : 'detail'
    }
  ]  
}

この形式だとどのHTTPメソッドを使えば良いのかよくわからないなぁ、と後から見て気がつきました。

どう解決するのが素直かな、と調べて回りましたが、シンプルにメソッド情報をつけるのが良さそうです。Paypalさんのドキュメントが参考になりました。

WebAPIの設計ノウハウはapigeeさんのWeb API Design - Crafting Interfaces that Developers Loveなど参考になる情報が出ていますが、やはり実際のシステムに適用していくとなると頭を抱えることが多くあります。

1つ目に挙げた複数の登録方法、などはよくあるパターンなんじゃないかと思います。
こういった設計ノウハウを共有しあって 利用されやすい WebAPIを作っていければいいなあ、と思います。

エンタープライズなシステム開発者の残業を減らすためにも！

明日の参加者はまだ登録されていないようなのでWebAPI設計に苦労された方がいましたら、是非登録してノウハウを教えていただければ幸いです。