WebAPIのプラクティス本「Web API ~The Good Parts~」を読んで参考になったことまとめ

はじめに

　オライリー社出版の「Web API ~The Good Parts~」というWeb APIの運用のプラクティス本があり、個人的に参考になった点のまとめです。基本的には引用になります。Web APIについて漠然と使っていたが、いざ作るとなると考え方が分からなくなり悩んでいたが、この本を読むことでだいぶ考え方がわかるようになってきました。内容もTwitterやFacebookがどうAPIを提供しているのか等具体例を交えて説明しているのでわかりやすくかなりの良書です。:)
　対象読者は以下です。

• Web APIの初学者
• Webについての基本的な知識を持つ方

Web APIの運用方針

基本的な考え方

　Web APIを運用していく上では、基本的に以下の考えで行うと良いです。そもそもWeb APIとは、社内のみの運用を除いては一般の知らないユーザに使ってもらうことで、より良いサービスを展開してもらって、さらにAPIを公開しているサーバ。

• 仕様が決まっているものに関しては仕様に従う
• 仕様が存在していないものに関してはデファクトスタンダードに従う
  • デファクトスタンダードに従うことによって、他人がAPIをみたときの理解が容易になるため、開発効率の向上や開発者のストレス軽減につながります。できるだけオリジナルの要素を排除して一般的に使われているような、公開の仕方をマネすると良いと思います。

エンドポイント（URI）の設計

覚えやすく、どんな機能を持つURIなのかがひと目で分かる

具体的には以下のような方針です。

• 短く入力しやすいURI
• 人間が呼んで理解できるURI
  • api.example.com/sv/uのようなURIだとユーザは"sv"が本当にserviceなのか"u"がuserなのかを判断できない。
• 大文字小文字が混在していないURI
  • 基本的にはすべて小文字でスネークケースを使うのがデファクトスタンダードです。
• 改造しやすいURI
  • ドキュメントをみなくてもエンドポイントのみで内容を推測できるようにすることが大切。
• サーバ側のアーキテクチャが反映されていない
  • api.example.com/cgi-bin/get_user.php?user=100のようなエンドポイントに関しては、ユーザにとっては「CGIを使っている」とか「PHPで実装されている」とかの情報は不要で、わざわざエンドポイントで示すことは、ユーザの開発ストレスにつながります。
• ルールが統一されている

バージョン運用について

• エンドポイントにバージョンを含める
  　以下のようにエンドポイントにバージョンを含めることで、APIを改善（JSON構造の変更etc.）し互換性を持たないことを明示することができる。
  • api.example.com\v1

- 旧バージョンのサポート期間を公示する
　v2を出してすぐにv1をサポートを完全終了すると、クライアントアプリケーションを作ってくれているユーザが移行に時間を設けることが難しく、利用してくれるユーザが離れてしまう可能性が高くなります。公式サイト等に公示しておき、最低でも1~2年間は旧バージョンをサポートしてあげることが大事です。

### HTTPメソッドを正しく使う

　HTTPには以下のようなメソッドが一般的に使われており、これらを正しい用法で使うことが大切です。

| メソッド名       |説明  |
|:-----------------|:------------------|
| GET             | リソースの取得 |
| POST           | リソースの新規登録 |
| PUT             |既存リソースの更新 |
| DELETE               |リソースの削除|
| PATCH             |リソースの一部変更|
| HEAD             |リソースのメタ情報の取得|

 例えば、「プロフィールの説明文を更新したい」という場合にはPOSTではなくPATCHを使ったりといった具合です。こうすることによって実装者がそのAPIへアクセスすることに意味を理解しやすくなります。ただ、HTMLのFormの場合はPOSTとGETのみしかサポートされていない場合があります。その時は、X-HTTP-Method-Overrideなどリクエストヘッダに利用したいメソッドを追記しておく方法とかがあります。


### エラーの返し方

- 適切なエラーコードを返す
    - エラーコードにも色々あるが、まずは以下を覚えておくと良い。
 
|ステータスコード       |意味  |
|:-----------------|:------------------|
| 100番台             |情報 |
| 200番台           | 成功 |
| 300番台             |リダイレクト |
| 400番台               |クライアント側のエラー|
| 500番台             |サーバ側のエラー|

- エラーの詳細を返す

　例えば"404 Not Found"がステータスコードが返ってきてもユーザはエンドポイントがそもそも間違っているのか、クエリの引数が間違っているのかが、一見分かりません。そのような場合に、レスポンスボディ等にエラーの詳細を返すことによって理解しやすくなります。

```json
{
    "error": {
        "message": "Not found user id included in the query",
        "info": "http://docs.example.com/api/v1"
    }
}

おわりに

　本には今回紹介した以外にもセキュリティはどうするか、最近のWeb APIの動向など多くの情報が盛り込まれていますので、気になった方はぜひ呼んでみてください！