20221013 (Web)API仕様書を作る理由

Transcript

1. (Web)API仕様書を作る理由 mabubu0203
2. お品書き - 前置き - 本題 - 後書き
3. 前置き - スライドで出てくる単語について - スライドで説明しないこと - タイトルについて - スライドを経て
4. スライドで出てくる単語について 1. (Web)API バックエンド(サーバーサイド)でAPIを提供しているWebアプリケーション 2. (Web)API仕様書 `1. (Web)API` の仕様が書いてあるもの ※ API仕様書をWebで読めるようにしたもの！というニュアンスではない 3. エンドポイント `1. (Web)API` で提供されている、 `URI` と `HttpMethod` の組み合わせ。
5. スライドで説明しないこと - 何故(Web)APIを作るのか？モノリシックでいいのでは？ - (Web)APIを作る！で決定している体 (テイ)でスライド作っています - APIとは？ - アプリケーション・プログラミング・インタフェース - (Web)APIとは？RESTful APIとは？ - 個人の習熟度で連想するものが異なると思っていて、そこの認識のズレは矯正しません - OpenAPI Specification - 私が強烈に推していますが、今回は範囲外です - Webで閲覧できる(Web)API仕様書って最高！ - 今回はそもそもドキュメントが用意されていない話をします
6. タイトルについて (Web)APIを実装する時機械(反射)的に、 コードと(Web)API仕様書のセットで納品しています。 「(Web)API仕様書を作る理由を咄嗟に説明できないな」と思ったので 「(Web)API仕様書が存在しない」ケースから考えてみました。
7. スライドを経て Q. 「あなたは(Web)API仕様書を作る理由を咄嗟に説明できますか？」 A. 「流暢に説明できないが、関連するスライドはこの資料ですね」
8. 本題 - 結論：(Web)API仕様書が存在しない際、何かが生まれる - (Web)API仕様書が存在しない例 - 分析：(Web)API仕様書が存在しない際、何かが生まれる - (Web)API仕様書を作らずとも何か生まれるじゃん - (Web)API仕様書を作る理由
9. 結論：(Web)API仕様書が存在しない際、何かが生まれる (Web)API仕様書が存在しない場合、 それっぽい何かがおれおれ個人メモとして善意で生みだされる気がします。 - エンドポイントを提供している Webアプリケーションの情報 - 環境毎のURL - RequestHeader - 正常系/異常系のふるまい - エンドポイント毎の記載内容 - URL/HttpMethod - リクエストに必要な情報 - RequestBody/QueryString - リクエストする上での前提情報 - レスポンスの期待値 - ResponseStatusCode - ResponseBody
10. (Web)API仕様書が存在しない例 (Web)API仕様書が存在しない例をケース毎に列挙します - ①(Web)APIを開発する側の場合 - ①-①新規開発中にJoinした場合 - ①-②グロース期間にJoinした場合 - ①-③古の保守をお願いされた場合 - ②(Web)APIを利用する側の場合 - ②-①立場がフロントエンド /モバイル開発などの場合 - ②-②社内の(Web)APIを利用したい全く別の PJTの場合
11. ①-①新規開発中にJoinした場合 YouにはこのPJTにJoinしてもらいたい 同じチームの Aさんが色々詳しいから、 わからないことあれば Aさんに聞いてね Aさん、これ(Web)API仕様書がないんですね、 どうやって(Web)APIを動作確認すればよろしいでしょうか？ これはですね、こんなリクエストで実行できますよ。 リクエストをSlackに貼りますね^^ Aさん、修正したのでそれでは正常に動きません。 新しいリクエストをSlackに貼りますね^^ ありがとうござい ます^^ 偉い人 Aさん Bさん You
12. ①-②グロース期間にJoinした場合 YouにはこのPJTにJoinしてもらいたい 同じチームの Aさんが色々詳しいから、 わからないことあれば Aさんに聞いてね Aさん、これ(Web)API仕様書がないんですね、 どうやって(Web)APIを動作確認すればよろしいでしょうか？ これはですね、こんなリクエストで実行できますよ。 リクエストをSlackに貼りますね^^ 私も自分が持ってるリクエストを Slackに貼りますね^^ 聞いたら教えてく れる、やさしい世 界だ^^ 偉い人 Aさん Bさん You
13. ①-③古の保守をお願いされた場合 Youにはこの動いている (Web)APIの運用・保守をお願いしたい 起動方法は Readme.mdと社内のドキュメントとメモ読んで試してみて これ(Web)API仕様書がないんですね、 (ドキュメントに書いてあるといいな ) 前任者が引き継ぎのメモ作ってるから、 それ通りにやれば大丈夫だとおもうよ ためしてガッテン、えいや 偉い人 You Aさん Bさん （がんばれー） （がんばれー...）
14. ②-①立場がフロントエンド/モバイル開発などの場合 YouにはこのPJTにJoinしてもらいたい バックエンドについては Aさんが色々詳しいよ Aさん、これ(Web)API仕様書がないんですね、 (Web)APIのI/Fってどうなっていますか？ これはですね、このメモに書いています。 これ通りに実行してみてください。 わからなくなったらまた声かけてくださいね。 ありがとうござい ます^^ 偉い人 Aさん You
15. ②-②社内の(Web)APIを利用したい全く別のPJTの場合 あのPJTに、hogeなAPIがあるって噂だ、使いたいな hogeなAPIありますね、 チームの人に実行方法とか聞いてこちらから連絡します hogeなAPI、 実行方法についてメモまとめたのでそれ渡しておきます わからなくなったら声かけてくださいね。 PJTの有識者 チームの有識者 You ありがとうござい ます^^
16. 分析：(Web)API仕様書が存在しない際、何かが生まれる おれおれ個人メモが蔓延すると... 以下、私見です。 書き手の立場で大事とすることがフォーマットとして確立され、 読み手はフォーマット毎に(Web)APIの仕様を読み解かなければならなくなる。 メモとして残っていたものだと、後続者は修正しにくい心情となりがち。 ※ 善意で書いたものにイチャモンつけにくいため、指摘しにくい
17. (Web)API仕様書を作らずとも何か生まれるじゃん おれおれ個人メモはメモなので、PJT公式のものではありません。 メモの保守と記載内容は保証されません。 (Web)APIのリバースエンジニアリング、車輪の再開発が PJT内で密かに行われるかもしれないです。
18. (Web)API仕様書を作る理由 結論： - (Web)API仕様書に書かれる内容は開発する上で最低限必要な情報となる - (Web)API仕様書がない場合、似て非なるものを個人が作りがち - 同人、二次創作、アンオフィシャル - 似て非なるものでもそこには時間が消費される 新規開発、運用・保守フェーズ問わず
19. 後書き - (Web)API仕様書を書く言語仕様・ツール - 開発者が(Web)API仕様書に求めるもの - 悩み：APIクライアントツールのリクエストサンプルとか - スライド作成にあたり
20. (Web)API仕様書を書く言語仕様・ツール - OpenAPI Specification - Swagger / Redoc / - RAML - API Blueprint - aglio
21. 開発者が(Web)API仕様書に求めるもの - P15の `(Web)API仕様書が存在しない際、何かが生まれる` の記載内容 - エンドポイントが網羅されており開発者自身が検索し辿り着ける事 - リクエスト/レスポンスのサンプルが記載されていること - 所定の場所にOnlyOneで置いてある事 - コード(実装)と対応した最新化(メンテナンス)された状態で置いてある事 - (Web)API仕様書を参照/編集できること - 人によっては編集することに抵抗を感じるものがいる - Microsoftで書かれているとライセンスが必要 - 共有ディレクトリに置かれていると Permissionが必要 ↑　`(Web)API仕様書を書く言語に挙げたもの` で標準実装されている
22. 悩み：APIクライアントツールのリクエストサンプルとか (Web)API仕様書があっても、`Postman` や `Talend API Tester` のリクエストちょーだ いといわれがち/いいがち。 課金でリクエストを共有する仕組みが存在しているが、課題として顕在化していない印 象。 (Web)APIのリクエストがデータに依存しているから実行までにデータを各々で調べてい る
23. スライド作成にあたり - 挿入した図 - かわいいフリー素材集 いらすとや で提供されている画像を利用しています - (Web)API仕様書が存在しない例について - フィクションです。ノンフィクションをマイルドにしているものもあり。
24. 完