K.S.ロジャース株式会社の民輪です。超久しぶりにQiita復帰してみました。以前の投稿が2年前。しかも超適当に記事を書いたせいでツッコミ入ったなーという記憶。ちなみに最近はJS方面にリソースさきつつ、WebGLやらないといけないのでThree.jsに手を出そうとしています。
一応これでも曲がりなりにもCTOもどきをやっているわけで真面目に記事書こうと一念発起しました（すぐに折れるかもしれない）。CTOとしてAPIの開発のマネジメントとかよくあるわけで、他の人とかに聞いてると案外グダッてる現場とかあるんだなぁと思いこの記事を書こうと思いました。
tl;dr
- APIの開発は必ずドキュメントを作成して、ドキュメントのモックを真とする。
- APIのドキュメントはエクセルなどではなく、弊社はApiaryを使っている（swaggerでもいいとは思う）
- APIの仕様を変更する場合にはドキュメントの変更まで戻る。サーバーサイドのエンジニアが勝手にやらない。
とお堅いルールをしっかり作っておくと、あれどうだったこうだったみたいなことがおきない。
まずはAPI設計に使うツールの候補
ドキュメント
- swagger
- Apiary(API Blueprint)
REST Client
- Postman
- Insomnia
などがあるかなーと思います。REST Clientは腐る程ありますが、有名どころだとこのへんでしょうか？あとは他にはJSON Schemeとかかなぁ。まぁ今回はこの2つを順番に見ていきましょう。
ドキュメント
swagger
まぁ、おそらく一番有名です。コード内にアノテーションっぽいのかけば自動生成してくれますよね。
利点
- https://github.com/zircote/swagger-php やLaravel/Railsに組み込めるcomposer/gemなども出てきており、ある程度エコシステムができているでしょうか。
- AWS API GatewayにSwagger定義を指定してインポートすることでAPI GatewayにAPIをセットアップできる。
などがあるかなーと。2つめのAPI Gatewayに組み込めるのはいいですよねー。
不満点
UIがダサいんですよねー。見る気が無くなるという。。。
Apiary
利点
- UIカッコイイ
- API Blueprintというmdっぽい感じでかけるのでかきやすい
- プレビュー機能が結構好き
不満点
- モックはApiary.ioにあげることにあるが有料
- ORACLEに買収された
- なんだかんだ変な書き方の部分があるといえばある
などありますが、Apiaryを採用しています。運用方法も最適化しやすくフロントエンドのエンジニアと連携がとりやすいです。
REST Client
Postman
https://www.getpostman.com/ で有名ですね。Chromeの拡張機能としてもインストール可能です。ただ、採用していない理由としてどうにもChromeの拡張機能としてインストールしたりするとUser-AgentがChromeになっちゃうんですよね。解決方法を調べたら出てきますがこれが気にくわない。。。アプリ開発ではUAのチェックは全エンドポイントでマストに入るので弾かれてしまいます。
Insomnia
https://insomnia.rest/ です。たしかElectronで書かれていたんだっけな。。。非常に良い点としてはGraphQLのClientも存在しています。
上記などから弊社ではInsomniaを採用しています。以前とあるプロジェクトでは、コマンド最強と思い込み全エンドポイントのcurlのshを用意しておき、爆速で叩きまくっていたこともありましたが反省しました。しんどいです。
API開発のフロー
こんな感じにしています。かなりAPIの仕様書にはレビューが入り、確定後変更がある場合には仕様書作成の最初の地点まで戻るようにしています。つまり、API設計は必ずモックが真であり、モックにならった実装をするようにしており、モックにならっていない場合にはバグではなくてもAPIの実装の修正をするようにしています。
たまにまだフローに慣れていないアプリのエンジニアからモックと少し違うので実際のAPIに合わせて実装しておきましたと言われる時がありますが、その時にはしっかりフローを守るように注意するようにしています。
API Blueprintを書く上で使えるツール
- Drafter: API Blueprintにエラーがないか調べてくれます
- vscode-apielements: VS Code用linter
- linter-api-blueprint: Atom用linter
- api-blueprint-sublime-plugin: Sublime用linter
です。Drafterはないと仕事にならないですね。自分はエンドポイントごとにmdで書いていき、最後に複数のmdファイルをcatしてapiary.apibとして吐き出した後、drafterにかけてpreviewするようにしています。
どんなAPI設計か？
ここで普段のAPI設計のノリを簡単に説明しようと思います。認証はJWTを使っているのですが、ぶっちゃけどんなプロジェクトでも認証まわり、登録周り、プロフ更新まわり、エラー処理まわりは同じ設計で使いまわせます。なのでその辺りはテンプレ化しちゃっています。
具体的には、
- エラー時のレスポンスフォーマット
- 成功時のレスポンスフォーマット
- httpレスポンスヘッダー
- 受け付けるhttpリクエストヘッダー
- ログイン処理 [/api/v1/sessions][POST]
- セッションのリフレッシュ [/api/v1/sessions/refresh][POST]
- 会員登録 [/api/v1/users][POST]
- プロフィール取得 [/api/v1/profile][GET]
- プロフィール更新 [/api/v1/profile/save][PATCH]
- マスターの取得 [/api/v1/defaults/masters][GET]
このあたりはどんなプロジェクトでも一緒じゃないでしょうか。なのであらかじめ共通で使い回せるようにフレームワーク化しておくとその後のAPIの設計が非常に楽です。実際に自分はテンプレを作っているのでサクサクAPI設計が終わります。
実際には
こんな感じで用意しています。本当はレスポンスのフォーマットでエンベロープを一番上のレイヤーに用意した方が良いかもなんですが、アプリの実装でEntityを定義する時にだるいーとの声があがるのでやめました。
ここからさらに詳細まで書くのはしんどいので、もしもっと詳細を知りたい人は個別に連絡ください笑
最後に
とまぁ、どっちかというとAPIの設計の思想というよりはAPI開発におけるマネジメントよりの話が多かったかも。次回の投稿はもっとコードを紹介したいなぁと思います。
いまだにWordとかエクセル/スプレッドシートで設計をしていてしんどい現場になっちゃってる人はこれを機にフローを変えて見てはいかがでしょうか？
Wantedlyでもブログ投稿してます
Techブログに加えて会社ブログなどもやっているので、気になった方はぜひ覗いてみてください。
https://www.wantedly.com/companies/ks-rogers