Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
20221013 (Web)API仕様書を作る理由
Search
mabubu0203
October 11, 2022
Education
0
520
20221013 (Web)API仕様書を作る理由
mabubu0203
October 11, 2022
Tweet
Share
More Decks by mabubu0203
See All by mabubu0203
バイブコーディングの紹介
mabubu0203
0
9
ペットの迷子を解決(20230929)
mabubu0203
0
420
20210927 転職活動のお話
mabubu0203
0
150
20220605 GraphQL実装してみた
mabubu0203
0
100
Other Decks in Education
See All in Education
著作権と授業に関する出前講習会/dme-2025-05-01
gnutar
0
200
実務プログラム
takenawa
0
6.5k
Human-AI Interaction - Lecture 11 - Next Generation User Interfaces (4018166FNR)
signer
PRO
0
470
Constructing a Custom TeX Ecosystem for Educational Institutions—Beyond Academic Typesetting
doratex
1
10k
20250611_なんでもCopilot1年続いたぞ~
ponponmikankan
0
100
Webリテラシー基礎
takenawa
0
6.6k
仮説の取扱説明書/User_Guide_to_a_Hypothesis
florets1
4
320
小さなチャレンジが生んだチームの大きな変化 -私のふりかえり探求の原点
callas1900
0
550
ARアプリを活用した防災まち歩きデータ作成ハンズオン
nro2daisuke
0
100
2025/06/05_読み漁り学習
nag8
0
150
Dashboards - Lecture 11 - Information Visualisation (4019538FNR)
signer
PRO
1
2.1k
SkimaTalk Tutorial for Students
skimatalk
0
1.8k
Featured
See All Featured
Testing 201, or: Great Expectations
jmmastey
43
7.6k
Git: the NoSQL Database
bkeepers
PRO
430
65k
Fashionably flexible responsive web design (full day workshop)
malarkey
407
66k
Build The Right Thing And Hit Your Dates
maggiecrowley
36
2.8k
Making Projects Easy
brettharned
116
6.3k
A Tale of Four Properties
chriscoyier
160
23k
Practical Orchestrator
shlominoach
189
11k
CoffeeScript is Beautiful & I Never Want to Write Plain JavaScript Again
sstephenson
161
15k
Gamification - CAS2011
davidbonilla
81
5.4k
The Language of Interfaces
destraynor
158
25k
A Modern Web Designer's Workflow
chriscoyier
695
190k
The Art of Programming - Codeland 2020
erikaheidi
54
13k
Transcript
(Web)API仕様書を作る理由 mabubu0203
お品書き - 前置き - 本題 - 後書き
前置き - スライドで出てくる単語について - スライドで説明しないこと - タイトルについて - スライドを経て
スライドで出てくる単語について 1. (Web)API バックエンド(サーバーサイド)でAPIを提供しているWebアプリケーション 2. (Web)API仕様書 `1. (Web)API` の仕様が書いてあるもの ※
API仕様書をWebで読めるようにしたもの!というニュアンスではない 3. エンドポイント `1. (Web)API` で提供されている、 `URI` と `HttpMethod` の組み合わせ。
スライドで説明しないこと - 何故(Web)APIを作るのか?モノリシックでいいのでは? - (Web)APIを作る!で決定している体 (テイ)でスライド作っています - APIとは? - アプリケーション・プログラミング・インタフェース
- (Web)APIとは?RESTful APIとは? - 個人の習熟度で連想するものが異なると思っていて、そこの認識のズレは矯正しません - OpenAPI Specification - 私が強烈に推していますが、今回は範囲外です - Webで閲覧できる(Web)API仕様書って最高! - 今回はそもそもドキュメントが用意されていない話をします
タイトルについて (Web)APIを実装する時機械(反射)的に、 コードと(Web)API仕様書のセットで納品しています。 「(Web)API仕様書を作る理由を咄嗟に説明できないな」と思ったので 「(Web)API仕様書が存在しない」ケースから考えてみました。
スライドを経て Q. 「あなたは(Web)API仕様書を作る理由を咄嗟に説明できますか?」 A. 「流暢に説明できないが、関連するスライドはこの資料ですね」
本題 - 結論:(Web)API仕様書が存在しない際、何かが生まれる - (Web)API仕様書が存在しない例 - 分析:(Web)API仕様書が存在しない際、何かが生まれる - (Web)API仕様書を作らずとも何か生まれるじゃん -
(Web)API仕様書を作る理由
結論:(Web)API仕様書が存在しない際、何かが生まれる (Web)API仕様書が存在しない場合、 それっぽい何かがおれおれ個人メモとして善意で生みだされる気がします。 - エンドポイントを提供している Webアプリケーションの情報 - 環境毎のURL - RequestHeader
- 正常系/異常系のふるまい - エンドポイント毎の記載内容 - URL/HttpMethod - リクエストに必要な情報 - RequestBody/QueryString - リクエストする上での前提情報 - レスポンスの期待値 - ResponseStatusCode - ResponseBody
(Web)API仕様書が存在しない例 (Web)API仕様書が存在しない例をケース毎に列挙します - ①(Web)APIを開発する側の場合 - ①-①新規開発中にJoinした場合 - ①-②グロース期間にJoinした場合 - ①-③古の保守をお願いされた場合
- ②(Web)APIを利用する側の場合 - ②-①立場がフロントエンド /モバイル開発などの場合 - ②-②社内の(Web)APIを利用したい全く別の PJTの場合
①-①新規開発中にJoinした場合 YouにはこのPJTにJoinしてもらいたい 同じチームの Aさんが色々詳しいから、 わからないことあれば Aさんに聞いてね Aさん、これ(Web)API仕様書がないんですね、 どうやって(Web)APIを動作確認すればよろしいでしょうか? これはですね、こんなリクエストで実行できますよ。 リクエストをSlackに貼りますね^^
Aさん、修正したのでそれでは正常に動きません。 新しいリクエストをSlackに貼りますね^^ ありがとうござい ます^^ 偉い人 Aさん Bさん You
①-②グロース期間にJoinした場合 YouにはこのPJTにJoinしてもらいたい 同じチームの Aさんが色々詳しいから、 わからないことあれば Aさんに聞いてね Aさん、これ(Web)API仕様書がないんですね、 どうやって(Web)APIを動作確認すればよろしいでしょうか? これはですね、こんなリクエストで実行できますよ。 リクエストをSlackに貼りますね^^
私も自分が持ってるリクエストを Slackに貼りますね^^ 聞いたら教えてく れる、やさしい世 界だ^^ 偉い人 Aさん Bさん You
①-③古の保守をお願いされた場合 Youにはこの動いている (Web)APIの運用・保守をお願いしたい 起動方法は Readme.mdと社内のドキュメントとメモ読んで試してみて これ(Web)API仕様書がないんですね、 (ドキュメントに書いてあるといいな ) 前任者が引き継ぎのメモ作ってるから、 それ通りにやれば大丈夫だとおもうよ
ためしてガッテン、えいや 偉い人 You Aさん Bさん (がんばれー) (がんばれー...)
②-①立場がフロントエンド/モバイル開発などの場合 YouにはこのPJTにJoinしてもらいたい バックエンドについては Aさんが色々詳しいよ Aさん、これ(Web)API仕様書がないんですね、 (Web)APIのI/Fってどうなっていますか? これはですね、このメモに書いています。 これ通りに実行してみてください。 わからなくなったらまた声かけてくださいね。 ありがとうござい
ます^^ 偉い人 Aさん You
②-②社内の(Web)APIを利用したい全く別のPJTの場合 あのPJTに、hogeなAPIがあるって噂だ、使いたいな hogeなAPIありますね、 チームの人に実行方法とか聞いてこちらから連絡します hogeなAPI、 実行方法についてメモまとめたのでそれ渡しておきます わからなくなったら声かけてくださいね。 PJTの有識者 チームの有識者 You
ありがとうござい ます^^
分析:(Web)API仕様書が存在しない際、何かが生まれる おれおれ個人メモが蔓延すると... 以下、私見です。 書き手の立場で大事とすることがフォーマットとして確立され、 読み手はフォーマット毎に(Web)APIの仕様を読み解かなければならなくなる。 メモとして残っていたものだと、後続者は修正しにくい心情となりがち。 ※ 善意で書いたものにイチャモンつけにくいため、指摘しにくい
(Web)API仕様書を作らずとも何か生まれるじゃん おれおれ個人メモはメモなので、PJT公式のものではありません。 メモの保守と記載内容は保証されません。 (Web)APIのリバースエンジニアリング、車輪の再開発が PJT内で密かに行われるかもしれないです。
(Web)API仕様書を作る理由 結論: - (Web)API仕様書に書かれる内容は開発する上で最低限必要な情報となる - (Web)API仕様書がない場合、似て非なるものを個人が作りがち - 同人、二次創作、アンオフィシャル - 似て非なるものでもそこには時間が消費される
新規開発、運用・保守フェーズ問わず
後書き - (Web)API仕様書を書く言語仕様・ツール - 開発者が(Web)API仕様書に求めるもの - 悩み:APIクライアントツールのリクエストサンプルとか - スライド作成にあたり
(Web)API仕様書を書く言語仕様・ツール - OpenAPI Specification - Swagger / Redoc / -
RAML - API Blueprint - aglio
開発者が(Web)API仕様書に求めるもの - P15の `(Web)API仕様書が存在しない際、何かが生まれる` の記載内容 - エンドポイントが網羅されており開発者自身が検索し辿り着ける事 - リクエスト/レスポンスのサンプルが記載されていること -
所定の場所にOnlyOneで置いてある事 - コード(実装)と対応した最新化(メンテナンス)された状態で置いてある事 - (Web)API仕様書を参照/編集できること - 人によっては編集することに抵抗を感じるものがいる - Microsoftで書かれているとライセンスが必要 - 共有ディレクトリに置かれていると Permissionが必要 ↑ `(Web)API仕様書を書く言語に挙げたもの` で標準実装されている
悩み:APIクライアントツールのリクエストサンプルとか (Web)API仕様書があっても、`Postman` や `Talend API Tester` のリクエストちょーだ いといわれがち/いいがち。 課金でリクエストを共有する仕組みが存在しているが、課題として顕在化していない印 象。
(Web)APIのリクエストがデータに依存しているから実行までにデータを各々で調べてい る
スライド作成にあたり - 挿入した図 - かわいいフリー素材集 いらすとや で提供されている画像を利用しています - (Web)API仕様書が存在しない例について -
フィクションです。ノンフィクションをマイルドにしているものもあり。
完