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
400
20221013 (Web)API仕様書を作る理由
mabubu0203
October 11, 2022
Tweet
Share
More Decks by mabubu0203
See All by mabubu0203
ペットの迷子を解決(20230929)
mabubu0203
0
340
20210927 転職活動のお話
mabubu0203
0
140
20220605 GraphQL実装してみた
mabubu0203
0
76
Other Decks in Education
See All in Education
世界のオープンソースロボットたち #1
shiba_8ro
0
120
CompTIA Security+ SY0-601 Resumo
mariliarochas
2
2.5k
小・中・高等学校における情報教育の体系的な学習を目指したカリキュラムモデル案/curriculum model
codeforeveryone
1
2k
week@tcue2024
nonxxxizm
0
510
Contentless Marketing
jonoalderson
0
1.5k
H5P-työkalut
matleenalaakso
4
35k
アニメに学ぶチームの多様性とコンピテンシー
terahide
0
170
Web Architectures - Lecture 2 - Web Technologies (1019888BNR)
signer
PRO
0
2.6k
困ったときのガイドライン / We Support You in Any Situation
yasulab
2
3.8k
Kaggle 班ができるまで
abap34
1
180
Flinga
matleenalaakso
2
13k
RSJ2024学術ランチョンセミナー「若手・中堅による国際化リーダーシップに向けて」資料 (河原塚)
haraduka
0
210
Featured
See All Featured
Embracing the Ebb and Flow
colly
84
4.4k
GraphQLとの向き合い方2022年版
quramy
43
13k
Testing 201, or: Great Expectations
jmmastey
38
7k
Six Lessons from altMBA
skipperchong
26
3.4k
Thoughts on Productivity
jonyablonski
67
4.3k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
231
17k
Teambox: Starting and Learning
jrom
132
8.7k
Optimizing for Happiness
mojombo
376
69k
Building Flexible Design Systems
yeseniaperezcruz
327
38k
The MySQL Ecosystem @ GitHub 2015
samlambert
250
12k
Reflections from 52 weeks, 52 projects
jeffersonlam
346
20k
[RailsConf 2023] Rails as a piece of cake
palkan
49
4.8k
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仕様書が存在しない例について -
フィクションです。ノンフィクションをマイルドにしているものもあり。
完