WEB APIを使う機会が増えてきました。
サービス間の連携やモバイルアプリのバックエンドだけでなく、SPAによってウェブサービスにも使います。

最近制作したウェブサービスでも、ググりつつもかなり悩みながらURLやレスポンスを設計した。
このままではまずいなと思い、オライリーの<a target="_blank" href="https://www.amazon.co.jp/gp/product/4873116864/ref=as_li_tl?ie=UTF8&camp=247&creative=1211&creativeASIN=4873116864&linkCode=as2&tag=suzu60c-22&linkId=3ee7967f19a3be85e7012ced58dd68ff">Web API: The Good Parts</a><img src="//ir-jp.amazon-adsystem.com/e/ir?t=suzu60c-22&l=am2&o=9&a=4873116864" width="1" height="1" border="0" alt="" style="border:none !important; margin:0px !important;" />を読みました。
知りたかったことが詳細に書かれており、一冊を通して体系化された設計を学べたように思います。

![book](/images/posts/170/179/book.jpg)

## Web API The Goog Parts

> 本書はWeb APIを開発する際して、どのように設計すればよいか、どのような点に気をつけて開発すればよいのかについて書かれた書籍です。

本書の設計思想は美しいAPIを目指している。
厳密な**REST API**ではなく、**現実的なAPIを「美しく」設計すること**に主眼が置かれている。
ただ基本的な考え方は同じで、URIからレスポンスが想像できるわかり易さと、ステートフル、HTTPメソッドに応じたインターフェースとなる。
言及されていないが**RESTful API**かな。
レスポンスボディはXMLではなくJSON形式。[GraphQL](https://graphql.org/learn/)の記述はなかったはず。

REST APIについては[Wiki](https://ja.wikipedia.org/wiki/Representational_State_Transfer)か[Qiita](https://qiita.com/TakahiRoyte/items/949f4e88caecb02119aa)がわかりやすい。本書を読むのが一番良いが。

読んでわかることは大まかに以下の３つになるかと思います。

1. **WEB APIを公開するための設計思想**
2. **世にあるサービスの設計がどうなっているか**
3. **Auth2.0やHTTPの仕様など、WEB APIに関する技術の解説**

本書はURLの設計からレスポンスデータ、HTTPステータスの設計を解説しながら上記の３つを絡めている。
内輪のサービスではなく公開を前提として、利便性やセキュリティと文化的な面も考慮されている。
文化的な面は、広く使われている単語やインターフェースにしようねといった意味。
アプリケーション側の処理も想定しながら進むため、実際の開発現場で必要な要素が多々ある。
バージョンを変える際の指針なんかは知る機会が少ない。

フロントエンドにとってもどういったデータなら作りやすい・使いやすいものになるかを考えられる。
例えば、ユーザページとサイトのページネーションをどう実現するか。
これが、世にあるサービス（TwitterやFacebookなど）の設計を比較してまとまっています。
URIとレスポンスには各サービスの特徴や共通する点の解説もしてくれます。

HTTPの仕様の解説もありがたい。
レスポンスのステータスコード自体は知っていたが、使い方のイメージが曖昧だった。
HTTPの仕様は[RFC (Reqest for Contents)](https://triple-underscore.github.io/RFC7231-ja.html)にまとめられ日本語もあるが、全て読もうとは思えなかった。
RFCに言及してステータスコードとレスポンスヘッダの解説も十分にある。

### APIを公開すること

本書ではサービスのAPIを公開することの重要性も説いています。
有名なところでは、TwitterがAPIを公開していることでサードパーティ製のアプリが増えユーザの利便性が高まりユーザが増えていきました。
また、APIの利用を前提としたサービスもあり[Twillio](https://www.twilio.com/)は電話の自動応答やSMS送信を提供している。

私自身、APIも含めて提供するサービスを夢想しています。
公開したら攻撃されそうでなんだか怖いと感じていました。
第６章では、APIのセキュリティ面の設計も解説があり大変助かりました。
**本書では、APIを公開するに当たってのチェックシートも用意されています。**
設計する際に、今一度読み返す。

### おわりに

全体的に解説はとてもわかり易いです。
フレームワークに依らない基礎の技術を学ぶ上で、初心者の方にも参考になるかと。
文章は煮え切らないところと、少々細かすぎる嫌いがあります。
著者の苦悩もなんだか伝わってくる。

設計には普遍的な正解が無いように思うが、ベースとなる考え方と照らし合わせて個々のサービスのベストな設計をしていきたい。



 <div
    class="amakuri-default-comment"
    style="text-align: left; line-height: 1.5em; margin-bottom: 10px; overflow:hidden; _zoom:1;"
  >
    <div class="amakuri-default-comment-image" style="float: left; margin: 0 20px 0 0;">
      <a
        target="_blank"
        href="https://www.amazon.co.jp/gp/product/4873116864/ref=as_li_tl?ie=UTF8&camp=247&creative=1211&creativeASIN=4873116864&linkCode=as2&tag=suzu60c-22&linkId=9ec87f36552237ff30ac6753137e12a1"
      >
        <img
          border="0"
          src="//ws-fe.amazon-adsystem.com/widgets/q?_encoding=UTF8&MarketPlace=JP&ASIN=4873116864&ServiceVersion=20070822&ID=AsinImage&WS=1&Format=_SL160_&tag=suzu60c-22"
        />
      </a>
      
      <img
        src="//ir-jp.amazon-adsystem.com/e/ir?t=suzu60c-22&l=am2&o=9&a=4873116864"
        width="1"
        height="1"
        border="0"
        alt
        style="border:none !important; margin:0px !important;"
      />
    </div>
    <div class="amakuri-default-comment-desc" style="overflow: hidden; _zoom:1;">
      <div class="amakuri-default-comment-title" style="margin-bottom: 0.5em;">
        <a href="https://amzn.to/2ll9aLM" target="_blank">Web API: The Good Parts</a>
      </div>
      <div
        class="amakuri-default-comment-posted"
        style="margin-bottom: 0.5em; font-size: small;"
      >Posted at 2019.07.15</div>
      <div class="amakuri-default-comment-platform">O'REILLY</div>
      <div class="amakuri-default-comment-label" style="margin-bottom: 0.5em;">水野 貴明 著</div>
      <div class="amakuri-default-comment-link" style="margin-top: 1em;">
        <a href="https://amzn.to/2ll9aLM" target="_blank">Amazonで詳細を見る</a>
      </div>
    </div>
  </div>


こちらは[Amazonのクラウドエンジニアが選ぶ技術書](https://amzn.to/2jZ3ZB0)にも選ばれています。

【技術書】RESTful APIを設計したくて「Web API The Good Parts」を読みました