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
370
20221013 (Web)API仕様書を作る理由
mabubu0203
October 11, 2022
Tweet
Share
More Decks by mabubu0203
See All by mabubu0203
ペットの迷子を解決(20230929)
mabubu0203
0
290
20210927 転職活動のお話
mabubu0203
0
130
20220605 GraphQL実装してみた
mabubu0203
0
57
Other Decks in Education
See All in Education
英語学習から海外発表までの流れ
yasulab
18
4.1k
Educació digital en l'adolescència
gonz1ale1
0
200
Прием на целевое обучение
pnuslide
0
4.7k
2024年度春学期 統計学 第13回 不確かな測定の不確かさを測る ― 不偏分散とt分布 (2024. 7. 4)
akiraasano
PRO
0
110
🎓 ChatGPT を組み込んだ24時間TA : 教育現場における LLM 活用の課題と改善
yasslab
PRO
0
600
みんなのコード2023年度活動報告・2024年度活動方針/Annual report2023
codeforeveryone
0
130
SelectAIでSQL研修の演習問題に挑む [Oracle]
nisshii
1
130
2024年度春学期 統計学 第4回 データを「分布」で見る (2024. 5. 2)
akiraasano
PRO
0
140
week@tcue2024
nonxxxizm
0
360
week6@tcue2024
nonxxxizm
0
450
Dashboards - Lecture 11 - Information Visualisation (4019538FNR)
signer
PRO
1
1.5k
Introduction - Lecture 1 - Next Generation User Interfaces (4018166FNR)
signer
PRO
1
3.3k
Featured
See All Featured
Building Adaptive Systems
keathley
34
2k
Optimizing for Happiness
mojombo
373
69k
Gamification - CAS2011
davidbonilla
78
4.9k
Let's Do A Bunch of Simple Stuff to Make Websites Faster
chriscoyier
502
140k
How to Ace a Technical Interview
jacobian
274
23k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
228
16k
The Power of CSS Pseudo Elements
geoffreycrofte
64
5.2k
Building Applications with DynamoDB
mza
89
5.8k
What’s in a name? Adding method to the madness
productmarketing
PRO
21
2.9k
Music & Morning Musume
bryan
43
5.9k
How to train your dragon (web standard)
notwaldorf
79
5.5k
Art, The Web, and Tiny UX
lynnandtonic
291
20k
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仕様書が存在しない例について -
フィクションです。ノンフィクションをマイルドにしているものもあり。
完