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
210
美しい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
14k
生産性向上チームとは?
korosuke613
1
1.3k
サイボウズの生産性を高める生産性向上チームと開発文化 / Development culture and EPT in Cybozu
korosuke613
4
970
テスト漏れを無くしたい!ワークフロー単位でトリガーを自由に設定したい要望
korosuke613
0
110
What will your future college life look like? 〜今後の大学生活をどのようにしますか?〜
korosuke613
0
68
ETロボコン2019 CS大会モデル[DA] - K-Lab
korosuke613
0
860
ETロボコン2019 地区大会モデル[DA] - K-Lab
korosuke613
0
770
人月の神話紹介
korosuke613
0
140
片山徹郎研究室紹介スライド2019
korosuke613
0
420
Other Decks in Programming
See All in Programming
クラウドサービスの 利用コストを削減する技術 - 円安の真南風を感じて -
pyama86
3
230
Iteratorでページネーションを実現する
sonatard
3
690
はじめてみよう量子プログラミング
itokoichi01
0
280
Pythonによるイベントソーシングへの挑戦と現状に対する考察 / Challenging Event Sourcing with Python and Reflections on the Current State
nrslib
3
780
Flutterアプリを生成AIで生成する勘所
rizumita
0
230
Applied NLP in the Age of Generative AI
inesmontani
PRO
3
1.1k
Cohesion in Modeling and Design
mploed
3
170
◯◯エンジニアになった理由
gessy0129
PRO
0
550
Assembling the Future: crafting the missing pieces of the Ruby on Wasm puzzle
skryukov
0
120
実践Dash - 手を抜きながら本気で作るデータApplicationの基本と応用 / Dash for Python and Baseball
shinyorke
2
210
CSC509 Lecture 01
javiergs
PRO
1
190
Removing Corepack
yosuke_furukawa
PRO
9
950
Featured
See All Featured
CoffeeScript is Beautiful & I Never Want to Write Plain JavaScript Again
sstephenson
158
15k
Writing Fast Ruby
sferik
623
60k
Happy Clients
brianwarren
96
6.6k
Building Your Own Lightsaber
phodgson
101
6k
JavaScript: Past, Present, and Future - NDC Porto 2020
reverentgeek
45
4.8k
Thoughts on Productivity
jonyablonski
67
4.2k
How to Ace a Technical Interview
jacobian
274
23k
GitHub's CSS Performance
jonrohan
1030
450k
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
26
1.9k
How to name files
jennybc
76
98k
Web Components: a chance to create the future
zenorocha
309
42k
Building Adaptive Systems
keathley
37
2.1k
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って何がいいの?