これまでの「自主開発アイテム」を使って仕様書を構成するお話です。実際に2か月後に作った仕様書があるので見てみてね。
どもども、こんにちは！夜に翌日のお弁当を作る生活を日常にしていきたい龍ちゃんです。お弁当といっても、お肉は日替わりで味付けして、ブロッコリーを80gにのっけてタッパーに入れておくという簡単なものですね。料理するのが面倒な時にはとても重宝します。ちょうどお米がなくなってAmazonで注文したところなのですが、「お米が好き」ということもあって一日に一合以上食べないように気を使っています。意識していないと平気で2合以上食べてしまうので、気を使っていきますね。
さて、今回は「API仕様書」についてのお話です。入社してから初めて作った物の一つでもあります。入社してから初めて本格的なチーム開発を行っているのですが、仕様書の大切さを学ぶことができたという想いが根底にあります。それでは初めて行きましょう。
仕様書はなぜ必要？
偉そうなことはあまりかけないのですが、「なぜAPI仕様書が必要なのか？」といった話から始めていこうと思います。なぜAPI仕様書は必要なのでしょうか？
これは、喧嘩が起きないようにするためというのがいい答えだと思っています。フロントエンドとバックエンドを構築する人が同じ場合は、自分で仕様を決定することができるので認識の齟齬が起きる確率は低くなっています。チーム開発の場合では、フロントエンドとバックエンドを構築する人が異なる場合が多くあります。好き勝手に構築を行うと、認識の齟齬が起きている状態で作成に入り結局修正という話にもなりかねません。こういった場合には、「自分は悪くない」と思っている人が二人いれば、喧嘩の始まりですね。
ちなみに、この喧嘩は「過去の自分」と「今の自分」の間でも発生します。実装する規模にもよりますが、どちらも同時に実装することはできません。なので、過去の実装を忘れてしまっていて過去のコードを見て、「なんだ？このくそコードは！書いたの誰だ？」ってコメントの後に「自分だわ」となったりするわけです。そういった忘れ防止にもAPI仕様書は良い効果を示してくれます。
API仕様書の定義
ここではAPI仕様書の定義をまとめておきたいと思います。
世の中のAPI仕様書見てみようの会
さて、いきなり説明を書いていくのも難しいので、世の中に公開されているAPI仕様書を見てみましょう。二つほどリンクを張っておきますね。
あまりAPI仕様書を見慣れていない方は、アレルギーを発症してしまいそうなリンクページになっています。あまり見慣れていない方は「Pinterest」の方から見てみるとよいかもしれません。PCで見る方が絶対にいいのでPCで見てください。
では、世の中の仕様書から記述してあることを抽出して、仕様書に書くことをまとめましょう。
仕様書に書くもの
さて、上記のサイトから仕様書に書くものをまとめたものを以下に出しておきます。
以上の4点を抑えておくと、APIの仕様書として最低限の体裁を保つことができるかと思います。日本語的に理解が難しい部分としては、「ステータスコードとメッセージ」「request・responseの仕様」の2点かと思うので説明を入れていきます。
ステータスコードについての説明は、これまでのシリーズでやっているのでこちらを読んでみてください。ステータスコードは、エラーの内容をコードで表現していますが、あまりなじみのない方からすると悲しい気持ちになりますよね。僕みたいな人のためにも、ステータスコードとそのコードの意味を文章で表現したメッセージを用意して返答する方が親切です。このあたり、世の中のAPIは英語表記で書かれていることが多いです。
request・responseの仕様については、「データのやり取りはJSON形式でJSONのルールはこう！」といった程度に考えると理解が早まるかと思います。このルール部分は、フロントエンドとの接続になるので、とても重要です。「このURLにはこのデータの受け皿がある」「このURLは項の構造でデータが返ってくる」といった情報を落とすことなく書き込んでおくことで、フロントエンドエンジニアが質問することなくAPIを使用することができます。
API仕様書を書いてみる
前章を踏まえて、APIの仕様書を作成してみたいと思います。
前提条件
仕様書を作成する前に前提条件について話をしていきます。今回は、REST APIの設計思想をベースにTODOリストを作成するAPI仕様書を構築します。REST APIについての説明はこちらから。
REST APIの仕様から考えると、URLは一つにしてHTTPメソッドの4つ（POST/GET/PUT/DELETE）で処理を振り分け、データのやり取りはJSONを使用するとなります。ここでのURLは仮に「/item」としておきましょう。データを保持するためのデータベースの仕様としては、上記の4つの項目を持っているとします。
以上の条件を踏まえて、仕様書に書くものごとに書いていきます。すべてのメソッドについての仕様書は膨大になるので、POSTメソッドを例として進めていきます。
また、今回は見やすさ重視のためスプレッドシートではなく、Figmaで各工程を書き進めていきます。
APIのURLと簡易説明
これはとてもシンプルです。対応するURL・HTTPメソッド・簡易な説明の3つで構成しています。簡易な説明は、書く人によって分量が異なるのが難点です。直感的にAPIの内容がわかることがベストだと思っています。
ステータスコードとメッセージ
さわりでも書きましたが、メッセージは英語で書かれることが多いです。今回は日本語でコミカルに文章を作成しました。ステータスコードについては、自分が調べてまとめた記事を書いているので、気になる方は読んでみてください。こちらです。
request・responseの仕様
ここでは、request・responseの仕様を決定していきます。POSTのrequestでは作成するデータを送信し、responseでは作成した結果を送信します。ここで決定することは、フロント側から何を送信し、API側で何のデータを作成するかというものです。
以下にrequest・responseの仕様を示しています。TODOリストで作成という手順で、必要となるデータとしては「task」の文字列のみとなります。「task」以外の「ID/created/state」は自動生成可能なパラメータなので、API側で作成すると決定します。
responseで仕様が二つあるのは、成功するパターンとエラーが発生するパターンの2つあります。ここの書き方すごく迷ったのですが、文字で書くパターンのほうが多いイメージでしたね。見やすさ重視で図を作りました。
ここで先輩から聞いた豆知識なのですが、「POSTのresponseには作成したデータを含めるとよい」らしいです。
request・responseのサンプル
ここでは、実際に動かせることができるサンプルを用意します。今回は、request・responseの仕様とほぼ似ている内容になってしまいますね。REST APIの思想を踏襲しているので、responseの返答にはURLを含ませています。
まとめ
今までの図を一つにまとめることで「POST /item」の仕様書が完成するわけですね。今回は、パーツ事に分割して書いているので、見やすくまとめることはできないのですが、本来ならスプレッドシートやエクセルを駆使して管理しやすくまとめておきます。
共有するドキュメントの場合は、WEBページなどでもあるのですが、チーム間での共有ならそこまで本気で作らなくてもいいですよね。とりあえず、関わる人間が見やすくわかりやすければオッケーなのですね。
終わりに
はー～お疲れ様でした。今回は、今までの自主開発アイテムシリーズのまとめ的な位置になっています。ちょっと長めの記事になったのでヘビーでしたね。
最近では、毎日のようにブログを作っているので、見やすい記事を作るために試行錯誤しています。これからもよい記事を作るために頑張っていきます。
誤字脱字はチェックしてますけど、見落としもあるはずなのでこっそり教えてください”(-“”-)”。あ！！おすすめ記事おいておきます。ぜひ見てね。
それではまた！
