Upgrade to Pro — share decks privately, control downloads, hide ads and more …

美しいWebAPIの作り方.pdf

Sponsored · Ship Features Fearlessly Turn features on and off without deploys. Used by thousands of Ruby developers. →
Futa HIRAKOBA
September 14, 2017

 美しいWebAPIの作り方.pdf

研究室の本紹介プレゼンで発表したスライドです

Futa HIRAKOBA

September 14, 2017

Transcript

38 slides
  1. KatLab 片山徹郎研究室 平成30年9月14日(金) 平木場 風太 紹介 Web API T h

    e G o o d P a r t s の紹介 ~美しいWebAPIの作り方 ~
  2. 紹介する本 Web API: The Good Parts • 著者: 水野 貴明

    • 発行月: 2014年11月 • ISBN: 978-4-87311-686-0 • 出版社: オライリージャパン Web APIの設計、開発、運用に ついての解説書。 XML over HTTP方式、JSON over HTTP方式を扱う。 11
  3. 設計の美しいWebAPIとは? 美しいAPI設計の“美しい”とは • よく考えられている • わかりやすく整理されている • 無駄がないなどの完成度の高さ 18 設計の“美しい”WebAPIは

    • 使いやすい - サードパーティ開発者の負担軽減 • 変更しやすい - 利用者に影響ない変更が可能 • 頑強である - 不正利用の防止、ダウンタイム低減 • 恥ずかしくない - サービス開発者の技術レベルを誇示
  4. 守るべき項目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
  5. 守るべき項目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
  6. エラーの表現 エラーの際は、 ステータスコード + エラー詳細 をクライアントに返す。 31 HTTPのレスポンスの先頭行に付けられる 例) HTTP/1.1

    200 OK Server: api.example.com ステータスコード • 適切なステータスコード を使用する。 • エラー詳細はステータス コードでは表現しきれな い詳細なエラー内容を含 める。 エラー詳細
  7. WebAPIを公開する際にできること • APIドキュメントの提供 公開したAPIを多くの人に利用してもらえるようになる第一歩。 API Blueprint(http://apiblueprint.org/)という便利なツールも 存在する。 • サンドボックスAPIの提供 本当のAPIとは別に用意されたテスト環境のこと。ユーザが自

    由にAPIを試すことができる。 • APIコンソールの提供 APIコンソールを提供することにより、API利用者はわざわざス クリプトなどを書かなくてもAPIを簡単に試すことができる。 Apigee(https://apigee.com)というAPIコンソールを生成する サービスも存在する。 33
  8. KatLab 夏休みの宿題 平成30年9月14日(金) 平木場 風太 紹介 Web API T h

    e G o o d P a r t s の紹介 ~美しいWebAPIの作り方 ~

More Decks by Futa HIRAKOBA

Other Decks in Programming