Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

mabubu0203
October 11, 2022

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

mabubu0203

October 11, 2022
Tweet

More Decks by mabubu0203

Other Decks in Education

Transcript

  1. (Web)API仕様書を作る理由
    mabubu0203

    View full-size slide

  2. お品書き
    - 前置き
    - 本題
    - 後書き

    View full-size slide

  3. 前置き
    - スライドで出てくる単語について
    - スライドで説明しないこと
    - タイトルについて
    - スライドを経て

    View full-size slide

  4. スライドで出てくる単語について
    1. (Web)API
    バックエンド(サーバーサイド)でAPIを提供しているWebアプリケーション
    2. (Web)API仕様書
    `1. (Web)API` の仕様が書いてあるもの
    ※ API仕様書をWebで読めるようにしたもの!というニュアンスではない
    3. エンドポイント
    `1. (Web)API` で提供されている、
    `URI` と `HttpMethod` の組み合わせ。

    View full-size slide

  5. スライドで説明しないこと
    - 何故(Web)APIを作るのか?モノリシックでいいのでは?
    - (Web)APIを作る!で決定している体 (テイ)でスライド作っています
    - APIとは?
    - アプリケーション・プログラミング・インタフェース
    - (Web)APIとは?RESTful APIとは?
    - 個人の習熟度で連想するものが異なると思っていて、そこの認識のズレは矯正しません
    - OpenAPI Specification
    - 私が強烈に推していますが、今回は範囲外です
    - Webで閲覧できる(Web)API仕様書って最高!
    - 今回はそもそもドキュメントが用意されていない話をします

    View full-size slide

  6. タイトルについて
    (Web)APIを実装する時機械(反射)的に、
    コードと(Web)API仕様書のセットで納品しています。
    「(Web)API仕様書を作る理由を咄嗟に説明できないな」と思ったので
    「(Web)API仕様書が存在しない」ケースから考えてみました。

    View full-size slide

  7. スライドを経て
    Q. 「あなたは(Web)API仕様書を作る理由を咄嗟に説明できますか?」
    A. 「流暢に説明できないが、関連するスライドはこの資料ですね」

    View full-size slide

  8. 本題
    - 結論:(Web)API仕様書が存在しない際、何かが生まれる
    - (Web)API仕様書が存在しない例
    - 分析:(Web)API仕様書が存在しない際、何かが生まれる
    - (Web)API仕様書を作らずとも何か生まれるじゃん
    - (Web)API仕様書を作る理由

    View full-size slide

  9. 結論:(Web)API仕様書が存在しない際、何かが生まれる
    (Web)API仕様書が存在しない場合、
    それっぽい何かがおれおれ個人メモとして善意で生みだされる気がします。
    - エンドポイントを提供している Webアプリケーションの情報
    - 環境毎のURL
    - RequestHeader
    - 正常系/異常系のふるまい
    - エンドポイント毎の記載内容
    - URL/HttpMethod
    - リクエストに必要な情報
    - RequestBody/QueryString
    - リクエストする上での前提情報
    - レスポンスの期待値
    - ResponseStatusCode
    - ResponseBody

    View full-size slide

  10. (Web)API仕様書が存在しない例
    (Web)API仕様書が存在しない例をケース毎に列挙します
    - ①(Web)APIを開発する側の場合
    - ①-①新規開発中にJoinした場合
    - ①-②グロース期間にJoinした場合
    - ①-③古の保守をお願いされた場合
    - ②(Web)APIを利用する側の場合
    - ②-①立場がフロントエンド /モバイル開発などの場合
    - ②-②社内の(Web)APIを利用したい全く別の PJTの場合

    View full-size slide

  11. ①-①新規開発中にJoinした場合
    YouにはこのPJTにJoinしてもらいたい
    同じチームの Aさんが色々詳しいから、
    わからないことあれば Aさんに聞いてね
    Aさん、これ(Web)API仕様書がないんですね、
    どうやって(Web)APIを動作確認すればよろしいでしょうか?
    これはですね、こんなリクエストで実行できますよ。
    リクエストをSlackに貼りますね^^
    Aさん、修正したのでそれでは正常に動きません。
    新しいリクエストをSlackに貼りますね^^
    ありがとうござい
    ます^^
    偉い人
    Aさん
    Bさん
    You

    View full-size slide

  12. ①-②グロース期間にJoinした場合
    YouにはこのPJTにJoinしてもらいたい
    同じチームの Aさんが色々詳しいから、
    わからないことあれば Aさんに聞いてね
    Aさん、これ(Web)API仕様書がないんですね、
    どうやって(Web)APIを動作確認すればよろしいでしょうか?
    これはですね、こんなリクエストで実行できますよ。
    リクエストをSlackに貼りますね^^
    私も自分が持ってるリクエストを
    Slackに貼りますね^^
    聞いたら教えてく
    れる、やさしい世
    界だ^^
    偉い人
    Aさん
    Bさん
    You

    View full-size slide

  13. ①-③古の保守をお願いされた場合
    Youにはこの動いている (Web)APIの運用・保守をお願いしたい
    起動方法は Readme.mdと社内のドキュメントとメモ読んで試してみて
    これ(Web)API仕様書がないんですね、
    (ドキュメントに書いてあるといいな )
    前任者が引き継ぎのメモ作ってるから、
    それ通りにやれば大丈夫だとおもうよ ためしてガッテン、えいや
    偉い人
    You
    Aさん Bさん
    (がんばれー)
    (がんばれー...)

    View full-size slide

  14. ②-①立場がフロントエンド/モバイル開発などの場合
    YouにはこのPJTにJoinしてもらいたい
    バックエンドについては Aさんが色々詳しいよ
    Aさん、これ(Web)API仕様書がないんですね、
    (Web)APIのI/Fってどうなっていますか?
    これはですね、このメモに書いています。
    これ通りに実行してみてください。
    わからなくなったらまた声かけてくださいね。 ありがとうござい
    ます^^
    偉い人
    Aさん
    You

    View full-size slide

  15. ②-②社内の(Web)APIを利用したい全く別のPJTの場合
    あのPJTに、hogeなAPIがあるって噂だ、使いたいな
    hogeなAPIありますね、
    チームの人に実行方法とか聞いてこちらから連絡します
    hogeなAPI、
    実行方法についてメモまとめたのでそれ渡しておきます
    わからなくなったら声かけてくださいね。
    PJTの有識者
    チームの有識者
    You
    ありがとうござい
    ます^^

    View full-size slide

  16. 分析:(Web)API仕様書が存在しない際、何かが生まれる
    おれおれ個人メモが蔓延すると...
    以下、私見です。
    書き手の立場で大事とすることがフォーマットとして確立され、
    読み手はフォーマット毎に(Web)APIの仕様を読み解かなければならなくなる。
    メモとして残っていたものだと、後続者は修正しにくい心情となりがち。
    ※ 善意で書いたものにイチャモンつけにくいため、指摘しにくい

    View full-size slide

  17. (Web)API仕様書を作らずとも何か生まれるじゃん
    おれおれ個人メモはメモなので、PJT公式のものではありません。
    メモの保守と記載内容は保証されません。
    (Web)APIのリバースエンジニアリング、車輪の再開発が
    PJT内で密かに行われるかもしれないです。

    View full-size slide

  18. (Web)API仕様書を作る理由
    結論:
    - (Web)API仕様書に書かれる内容は開発する上で最低限必要な情報となる
    - (Web)API仕様書がない場合、似て非なるものを個人が作りがち
    - 同人、二次創作、アンオフィシャル
    - 似て非なるものでもそこには時間が消費される
    新規開発、運用・保守フェーズ問わず

    View full-size slide

  19. 後書き
    - (Web)API仕様書を書く言語仕様・ツール
    - 開発者が(Web)API仕様書に求めるもの
    - 悩み:APIクライアントツールのリクエストサンプルとか
    - スライド作成にあたり

    View full-size slide

  20. (Web)API仕様書を書く言語仕様・ツール
    - OpenAPI Specification
    - Swagger / Redoc /
    - RAML
    - API Blueprint
    - aglio

    View full-size slide

  21. 開発者が(Web)API仕様書に求めるもの
    - P15の `(Web)API仕様書が存在しない際、何かが生まれる` の記載内容
    - エンドポイントが網羅されており開発者自身が検索し辿り着ける事
    - リクエスト/レスポンスのサンプルが記載されていること
    - 所定の場所にOnlyOneで置いてある事
    - コード(実装)と対応した最新化(メンテナンス)された状態で置いてある事
    - (Web)API仕様書を参照/編集できること
    - 人によっては編集することに抵抗を感じるものがいる
    - Microsoftで書かれているとライセンスが必要
    - 共有ディレクトリに置かれていると Permissionが必要
    ↑ `(Web)API仕様書を書く言語に挙げたもの` で標準実装されている

    View full-size slide

  22. 悩み:APIクライアントツールのリクエストサンプルとか
    (Web)API仕様書があっても、`Postman` や `Talend API Tester` のリクエストちょーだ
    いといわれがち/いいがち。
    課金でリクエストを共有する仕組みが存在しているが、課題として顕在化していない印
    象。
    (Web)APIのリクエストがデータに依存しているから実行までにデータを各々で調べてい

    View full-size slide

  23. スライド作成にあたり
    - 挿入した図
    - かわいいフリー素材集 いらすとや で提供されている画像を利用しています
    - (Web)API仕様書が存在しない例について
    - フィクションです。ノンフィクションをマイルドにしているものもあり。

    View full-size slide