こんにちは、タロウです。

しばらく前に開催したバックエンドMTGの第3回の様子を紹介します！

今回は・・

オフラインで全員参加でした！が、
写真が残っていません。

インターフェース仕様書をもとに実装する機会があり、
その中で改めて気をつけたいことをライトにお話しました！

テーマ

「こんなIFはやめてくれ！」
Speaker: タロウ

某決済システムを導入する開発があり、
インターフェース仕様書(以降、IF仕様書)を見て実装する機会が多くありました。

その中でも少し混乱したところがあったので、
自分達が作成したIF仕様書で同じように困った人を生み出さないよう
今一度振り返るテーマとしました！

同じ金額の項目は型を統一したい！

リクエストに決済金額を設定してPOSTした際に、
レスポンスにリクエストで設定した値が返却されます。

記載例や型が違うのでやや混乱してしまいました。

ドキュメント類のフォーマットを統一したい！

ドキュメントによって拡張子がバラバラで、至る所に散らばっている・・
大きいプロジェクトで同じような経験のあるかたは多いのではないでしょうか？

煩雑なドキュメントはそのまま誰も見ることのない資料になりかねないので、
開きやすい、読みやすい、メンテしやすいフォーマットで統一して管理して行きたいです。

レスポンスイメージは表現したい！

どういう単位で、どの部分が繰り返し項目なのか読み解けば分かりそうですが、
実際にAPIを叩かないと、正しいのかが判断できません。

レスポンスイメージがあると、parseするだけで正しい値を返すスタブが作れたりと、
後戻りの必要を極力無くすことができます。

さいごに

開発する上で切り離すことのできないIF仕様書でしたが、今一度気をつけたい3選でした。

他にも気をつけなければいけないことや管理方法はたくさんありますが、
作成する時は、メンテナンス性と読み解く開発者の負担を極力減らすことのできる
IF仕様書を作成していきましょう。