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
12
ペットの迷子を解決(20230929)
mabubu0203
0
420
20210927 転職活動のお話
mabubu0203
0
150
20220605 GraphQL実装してみた
mabubu0203
0
100
Other Decks in Education
See All in Education
Gaps in Therapy in IBD - IBDInnovate 2025 CCF
higgi13425
0
500
Education-JAWS #3 ~教育現場に、AWSのチカラを~
masakiokuda
0
180
検索/ディスプレイ/SNS
takenawa
0
8.1k
仮説の取扱説明書/User_Guide_to_a_Hypothesis
florets1
4
320
AIの時代こそ、考える知的学習術
yum3
2
180
The Art of Note Taking
kanaya
1
140
諸外国の理科カリキュラムにおけるビッグアイデアの構造比較
arumakan
0
350
モンテカルロ法(3) 発展的アルゴリズム / Simulation 04
kaityo256
PRO
7
1.3k
JOAI2025講評 / joai2025-review
upura
0
180
SkimaTalk Tutorial for Students
skimatalk
0
1.8k
著作権と授業に関する出前講習会/dme-2025-05-01
gnutar
0
200
20250611_なんでもCopilot1年続いたぞ~
ponponmikankan
0
120
Featured
See All Featured
Fireside Chat
paigeccino
37
3.5k
Practical Tips for Bootstrapping Information Extraction Pipelines
honnibal
PRO
21
1.3k
Learning to Love Humans: Emotional Interface Design
aarron
273
40k
実際に使うSQLの書き方 徹底解説 / pgcon21j-tutorial
soudai
PRO
181
54k
The Pragmatic Product Professional
lauravandoore
35
6.7k
Speed Design
sergeychernyshev
32
1k
Documentation Writing (for coders)
carmenintech
72
4.9k
XXLCSS - How to scale CSS and keep your sanity
sugarenia
248
1.3M
Bootstrapping a Software Product
garrettdimon
PRO
307
110k
Balancing Empowerment & Direction
lara
1
460
Improving Core Web Vitals using Speculation Rules API
sergeychernyshev
18
990
Optimising Largest Contentful Paint
csswizardry
37
3.3k
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仕様書が存在しない例について -
フィクションです。ノンフィクションをマイルドにしているものもあり。
完