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
美しいWebAPIの作り方.pdf
Search
Futa HIRAKOBA
September 14, 2017
Programming
0
240
美しいWebAPIの作り方.pdf
研究室の本紹介プレゼンで発表したスライドです
Futa HIRAKOBA
September 14, 2017
Tweet
Share
More Decks by Futa HIRAKOBA
See All by Futa HIRAKOBA
terraform plan 結果の検証を自動化するぞ! with Conftest / Testing terraform plan with Conftest
korosuke613
0
15k
生産性向上チームとは?
korosuke613
1
1.4k
サイボウズの生産性を高める生産性向上チームと開発文化 / Development culture and EPT in Cybozu
korosuke613
4
1k
テスト漏れを無くしたい!ワークフロー単位でトリガーを自由に設定したい要望
korosuke613
0
120
What will your future college life look like? 〜今後の大学生活をどのようにしますか?〜
korosuke613
0
76
ETロボコン2019 CS大会モデル[DA] - K-Lab
korosuke613
0
920
ETロボコン2019 地区大会モデル[DA] - K-Lab
korosuke613
0
830
人月の神話紹介
korosuke613
0
160
片山徹郎研究室紹介スライド2019
korosuke613
0
490
Other Decks in Programming
See All in Programming
layerx_20241129.pdf
kyoheig3
2
290
Jakarta EE meets AI
ivargrimstad
0
230
14 Years of iOS: Lessons and Key Points
seyfoyun
1
770
開発者とQAの越境で自動テストが増える開発プロセスを実現する
92thunder
1
180
Criando Commits Incríveis no Git
marcelgsantos
2
170
テストケースの名前はどうつけるべきか?
orgachem
PRO
0
130
.NET 9アプリをCGIとして レンタルサーバーで動かす
mayuki
1
770
生成AIでGitHubソースコード取得して仕様書を作成
shukob
0
200
Fibonacci Function Gallery - Part 1
philipschwarz
PRO
0
200
Zoneless Testing
rainerhahnekamp
0
120
「Chatwork」Android版アプリを 支える単体テストの現在
okuzawats
0
180
たのしいparse.y
ydah
3
120
Featured
See All Featured
The Psychology of Web Performance [Beyond Tellerrand 2023]
tammyeverts
45
2.2k
Distributed Sagas: A Protocol for Coordinating Microservices
caitiem20
330
21k
Large-scale JavaScript Application Architecture
addyosmani
510
110k
A Tale of Four Properties
chriscoyier
157
23k
The Power of CSS Pseudo Elements
geoffreycrofte
73
5.4k
Navigating Team Friction
lara
183
15k
Building Adaptive Systems
keathley
38
2.3k
Building a Scalable Design System with Sketch
lauravandoore
460
33k
Designing for humans not robots
tammielis
250
25k
The Language of Interfaces
destraynor
154
24k
The Invisible Side of Design
smashingmag
298
50k
Music & Morning Musume
bryan
46
6.2k
Transcript
KatLab 片山徹郎研究室 平成30年9月14日(金) 平木場 風太 紹介 Web API T h
e G o o d P a r t s の紹介 ~美しいWebAPIの作り方 ~
背景1 2 家計簿サービスを作ったぞ! いろんな人に使ってもらいたいな〜
背景2 3 そうだ! WebAPIを作ってプログラマ達の力 を借りよう!! プログラマ軍団
背景3 4 でもWebAPIの設計ってどうやんの? HTTPもサーバもわかるけど… うおっ
アジェンダ 1. 背景 2. WebAPIとは 3. 紹介する本の概要 4. 美しいWebAPIを作るには 5
6 美しいWebAPIの作り方 WebAPIの概要 まずはWebAPIを おさらいしよう!
WebAPIとは • HTTPプロトコルを利用してネットワーク越し に呼び出すAPI(Application Programming Interface)のこと • あるURIにアクセスすることで、サーバ側の情 報を書き換えたり、サーバ側に置かれた情報を 取得できたりすることができるWebシステム。
• プログラムからサービスに容易にアクセスでき る。 7
実際にWebAPIを利用してみる 利用API:鯖江市コミュニティバス(つつじバス) ⚫ 福井県鯖江市で運行しているバス。 ⚫ 時刻表、バス停、走行中バスの座標や、運行情報等をWebAPIとして提供して いる。 ⚫ http://www.city.sabae.fukui.jp/users/tutujibus/web-api/web-api.html 8
“運行状況に関するお知らせ” を確認する ← APIの使い方。 エンドポイント、リ クエストパラメータ、 レスポンスを確認し ておく。 ↓ ブラウザで利用。
(全てのAPIがブラウザで利用できるわけではない) 9
10 美しいWebAPIの作り方 Web API The Good Parts の概要 この本は何??
紹介する本 Web API: The Good Parts • 著者: 水野 貴明
• 発行月: 2014年11月 • ISBN: 978-4-87311-686-0 • 出版社: オライリージャパン Web APIの設計、開発、運用に ついての解説書。 XML over HTTP方式、JSON over HTTP方式を扱う。 11
各章の概要1 1章 Web APIとは何か → WebAPIを取り巻く現状と本書の内容の活かし方など。 2章 エンドポイントの設計とリクエストの形式 →クライアントからサーバに対して行うアクセスの設計など。 3章
レスポンスデータの設計 →リクエストに対して返されるレスポンスデータの構造の設 計など。 12
各章の概要2 4章 HTTPの仕様を最大限利用する(省略) → HTTPの仕様をどのようにAPIに反映させるべきか。 5章 設計変更をしやすいWeb APIを作る(省略) → 公開したAPIを安全に修正する方法。
6章 堅牢なWebAPIを作る(省略) → 想定しないアクセスによる影響を最小限に抑えるた めのセキュリティや安定性。 13
各章の概要3 付録A WebAPIを公開する際にできること → WebAPIにおいて、考慮すべき設計以外の事柄の紹介。 付録B WebAPIチェックリスト → 本書で触れた内容をきちんと設計に反映できている かを簡単にチェックするための一覧表。
14
APIを公開するということ APIを公開することでさまざまな付加価値 を他の企業や個人が提供してくれる。 サービスの価値や情報の質が向上する可 能性がある! 15 したがって
例えば家計簿サービスを公開する 16 開発者 ユーザ 家計簿サービス WebAPI サードパーティ開発者 家計簿アプリ 家計簿ブラウザ拡張機能 サービス価値の向上
WebAPIを美しく設計しよう しかし、先の例は美しいWebAPIである場合! 17 美しくないWebAPI 美しいWebAPI したがって、 WebAPIを美しく設計することが大事
設計の美しいWebAPIとは? 美しいAPI設計の“美しい”とは • よく考えられている • わかりやすく整理されている • 無駄がないなどの完成度の高さ 18 設計の“美しい”WebAPIは
• 使いやすい - サードパーティ開発者の負担軽減 • 変更しやすい - 利用者に影響ない変更が可能 • 頑強である - 不正利用の防止、ダウンタイム低減 • 恥ずかしくない - サービス開発者の技術レベルを誇示
美しいWebAPIを作る際の重要な原則 本書の思想の根幹をなす重要な原則 • 標準仕様が決まっているものに関しては仕様に従う • 標準仕様が存在していないものに関してはデファ クトスタンダードに従う すでにあるルールに従うことで、開発したAPIを利 用者が容易に利用できたり、既存のクライアントラ イブラリの流用が可能になったりする。
→ エコシステムの拡大 19
20 美しいWebAPIの作り方 エンドポイントの 設計 入口はわかりやすい方が 良い!!
重要な原則 APIにアクセスするためのURI 例) ToDoリストでユーザ情報を取得するAPIのエンドポイント → https://api.example.com/v1/users/me 21 原則 覚えやすく、 どんな機能を持つURIなのかがひと目でわかる
エンドポイント
守るべき項目1 • 短く入力しやすいURI 悪い例 http://api.example.com/service/api/search 良い例 http://api.example.com/search • 大文字小文字が混在していないURI 悪い例
http://api.example.com/Users/12345 良い例 http://api.example.com/users/12345 • サーバ側のアーキテクチャが反映されていないURI 悪い例 http://api.example.com/cgi-bin/get_user.php?user=100 このURIを見るだけで、このAPIが恐らくPHPで書かれていてCGIとして動作し て ることがわかる。 22
守るべき項目2 23 • 人間が読んで理解できるURI 悪い例 http://api.example.com/sv/u/ • 改造しやすい(Hackebleな)URI 悪い例 •
ルールが統一されたURI 悪い例 友達の情報を取得するAPI http://api.example.com/friend?id=100 メッセージの投稿 http://api.example.com/friend/100/message
HTTPメソッドに合わせた処理をする1 24 HTTPでのアクセス時に指定する命令。 例) GET /v1/users/123 HTTP/1.1 Host: api.example.com HTTPメソッド
HTTPメソッドに合わせた処理をする2 それぞれの目的に応じて適切にメソッドを使い分ける 25
26 美しいWebAPIの作り方 レスポンスデータ の設計 プログラムに優しい手紙 を書こう!
データフォーマット レスポンスデータでどういったデータフォーマット (構造化データの表現方法)を採用するかを決める。 27 JSONをデフォルトとして対応し、 必要があればXMLにも対応する! JavaScript Object Notationの略。 ポピュラー。
JSON Extensible Markup Languageの 略。昔はポピュラー。 XML
階層的 or フラット? 同じデータでも、フラットに表すことも階層的に表す こともできる。どちらにすべきだろうか? 上の例の場合、senderとreceiverのようにどちらも同じ ユーザという構造を表しているので、階層構造で表現 した方が良いと言える。 28 階層的に表す場合
フラットに表す場合
階層構造がいいのか? では、データはすべて階層的にするべきだろうか? 上の例の場合、単に複数項目をまとめたいためだけに 階層構造にしている為、コードを処理する上でも見た 目的にもあまり違いが無い。 そのため、フラットに表した方が良いと言える。 29 階層的に表す場合 フラットに表す場合
階層的 or フラット? 結論 結論としては、 なるべくフラットにすべきだが、階層化した 方が絶対に良い場合は階層化もあり というのが正しいルールと言える。(Googleスタイル ガイドにも書かれている。) 30
エラーの表現 エラーの際は、 ステータスコード + エラー詳細 をクライアントに返す。 31 HTTPのレスポンスの先頭行に付けられる 例) HTTP/1.1
200 OK Server: api.example.com ステータスコード • 適切なステータスコード を使用する。 • エラー詳細はステータス コードでは表現しきれな い詳細なエラー内容を含 める。 エラー詳細
32 美しいWebAPIの作り方 その他・まとめ もう少しで終わり
WebAPIを公開する際にできること • APIドキュメントの提供 公開したAPIを多くの人に利用してもらえるようになる第一歩。 API Blueprint(http://apiblueprint.org/)という便利なツールも 存在する。 • サンドボックスAPIの提供 本当のAPIとは別に用意されたテスト環境のこと。ユーザが自
由にAPIを試すことができる。 • APIコンソールの提供 APIコンソールを提供することにより、API利用者はわざわざス クリプトなどを書かなくてもAPIを簡単に試すことができる。 Apigee(https://apigee.com)というAPIコンソールを生成する サービスも存在する。 33
WebAPIチェックリスト 本書には、 WebAPIチェッ クリストが付録 している。 WebAPI開発時 に役立てること ができる。 34 (一部抜粋)
その他大事なこと • 認証にはOAuth 2.0を使う。 • 個人情報など特定のユーザ以外に漏洩したくな い情報がある場合はHTTPSを使う。 • APIのバージョンの更新は最小限にとどめ後方 互換性に注意する。
• APIのバージョンはメジャーバージョンをURI に含める。 • 実際はもっとたくさんある。 35
まとめ WebAPIを公開するとサービスの価値が向上する 36 • 標準仕様、またはデファクトスタンダードに 従う。 • 使いやすい、変更しやすい、頑強である、恥 ずかしくないWebAPIを作る。 WebAPIを美しく設計する
そのためには
KatLab 夏休みの宿題 平成30年9月14日(金) 平木場 風太 紹介 Web API T h
e G o o d P a r t s の紹介 ~美しいWebAPIの作り方 ~
38 美しいWebAPIの作り方 美しいAPIを 公開するメリット APIって何がいいの?