【初心者】Web APIの設計基礎【オライリー】

サービス

公開:2020年11月10日更新:2020年11月10日

どうも、えんつかです。

APIを利用したことはあるけど、

実際に開発する時はどんなことに配慮して設計すれば良いんだろうか。
現場で提供しているけど、どんなことを意識しているのだろうか。

そんな事を抱いている方がいるのではないかと思います。
私もその一人です。で、オライリーのWeb API The Good Partsを読みましたので、自分の頭の中の整理も含めて、サクッと簡単にまとめました。

【初心者】Web APIの設計基礎【オライリー】

まず、オライリーのWeb API The Good Partsの感想ですが、本の構成が個人的には理解しやすかったです。なぜ、Web APIが必要なのかから始まり、クライアント視点・サーバー視点・メンテナンス・セキュリティと棲み分けがちゃんとされていました。ので、API開発始めの方向けに良書なのかと思いました。

では、本書の構成と同じ形で以下の様にざっくりといきます！

何をAPIで公開するべきか/なぜAPI設計を美しくするのか
クライアント視点(エンドポイントの設計)
サーバー視点(レスポンスデータの設計)
設計変更しやすいAPI設計(メンテナンス)
堅牢なAPI設計(セキュリティ)

何をAPIで公開するべきか/なぜAPI設計を美しくするのか

APIの説明は割愛するとして、、、
自分が開発者だとして、どこまでAPIで対応するのか、なぜAPI設計を美しくするか疑問でした。美しく設計すると、ぱっと思いつくとメンテナンス性(保守・拡張)良いよねと思いますが、じゃ具体的にどうすると何が誰にとってどう良いの？がさっぱりなんですよね。言うは易し行うは難し。

てことで、結論、こんな感じです。

何をAPIで公開するべきか→そのサービスができることをすべて。ECサイトであれば、検索、購入、変更等々。
なぜAPI設計を美しくするか→①使いやすい(クライアント視点)②変更しやすい(サーバー視点)③頑強である(セキュリティ)

API設計を美しくする理由については、なんとなくわかるかと思いますが、具体的に、次移行で深ぼっていきます。

なぜAPI設計を美しく(クライアント視点・エンドポイントの設計)

結論、以下の理由です。

利用者/開発者がどんなリソースか覚えやすく/どんな機能をもつかひと目でわかるようにできる。

具体的には、
・覚えやすく、どんな機能を持つURIなのかひとめでわかる
・短く入力しやすいURI
・人間が読んで理解できるURI
・大文字小文字が混在しないURI
・サーバー側の設計(言語・ディレクトリ構造等)が反映されていないURI
・ルールが統一されてURI
です。

例えば、
http://api.example.com/service/api/search
は、より簡単に記述できますよね。
http://api.example.com/search
なぜなら、すでにapiという記述がありますし、なんらかのサービスでapiを提供しているのに、serviceを入れるのは冗長ですよね。

また、HTTPメソッドはAPIエンドポイントと切れない関係にあり、APIアクセス方法として同時に考えなければいけません。

HTTPメソッドで主要なのはGET、POSTですが、API設計にはその他を利用することが好ましいようです。

GET：一覧取得(エンドポイント例：http://api.example.com/v1/users)
POST：新規登録(エンドポイント例：http://api.example.com/v1/users)
PUT：情報更新(エンドポイント例：http://api.example.com/v1/users/:id)
PATCH：情報を部分的に更新(エンドポイント例：http://api.example.com/v1/users/:id)
DELETE：情報の削除(エンドポイント例：http://api.example.com/v1/users/:id)

あるデータの集合と、個々のデータをエンドポイントとして表現し、HTTPのメソッドで操作を表していく考え方はWeb API設計の基本中の基本で多くのAPIがこれに沿っているようです。この考え方をRESTful APIとも呼びます。

なぜAPI設計を美しく(サーバー視点・レスポンスデータの設計)

レスポンスデータ設計で重要なことはざっくり以下の通り

基本的にはJSON形式(デファクトスタンダード)
レスポンスをできる限りフラットな構造
各データ名が簡潔で理解しやすく、適切な複数・単数を用いる

データフォーマットには大きくJSONとXMLがあるようですが、最近ではJSONが多く利用されており事実上のデファクトスタンダードになっているようです。必要があれば、XMLにも対応するといったところでしょうか。

データフォーマットの記述には、Googleが推奨するのはキャメルケースですが、他の主要なサービスではスネークケースを用いていることもあり、そのサービス内でどの様に記述していくかルール決めとなりそうです。

フラットな構造とは、プロパティをオブジェクトでさらに包まないようにすることです。例えば、以下の感じです。

・フラットでない構造
“receiver”:{
“id”: 112121,
“name”:”aiueo”,
}
・フラットな構造
”receiverId”:112121,
“receiverName”:aiueo,

データ名が簡潔等は、エンドポイント設計と同じですね。

なぜAPI設計を美しく(設計変更しやすいAPI設計・メンテナンス)

ポイントは以下の感じです。

APIのバージョンの更新は最低限に留め、後方互換性に配慮
APIのバージョンはバージョンナンバーをURIに含める
提供終了はすぐに行うのではなく最低6ヶ月行う

APIのバージョン管理は、URIに組み込むのが良いそうです。例えば以下URIのv2はバージョンを示します。

http://api.tumblr.com/v2/blog

良くないのは、newapiとかの名前をつけてしまうことですね。これだと拡張性に乏しくなってしまいます。

バージョンを変える際の指針としては、
後方互換性を保つことができれば可能な変更は可能なかぎり同じバージョンで対応。バージョンを上げるのは、どうしても後方互換性を保ったまま修正を行うことが難しい場合にのみ上げるべきのようです。

なぜAPI設計を美しく(堅牢なAPI設計・セキュリティ)

ポイントは次の通り

個人情報など特定のユーザー以外に漏洩したくない場合HTTPSを利用
セキュリティ強化につながるHTTPヘッダをつける
レートリミットを設けて過度のアクセスによる負荷を防ぐ

HTTPSの通信方式はAPIに限らず暗号化をして通信情報がわからなくすることができるので、重要です。ただ、HTTPSだけでは不十分なことがあります。

そのために、ヘッダを設定して対策を行います。セキュリティ関係のHTTPヘッダは以下の通り。(HASHはhash値)

X-Content-Type-Options : nosniff
X-XSS-Protection : 1; mode=block
X-Frame-Options : deny
Content-Security-Policy : default-src ‘none’
Strict-Transport-Security : max-age=15151515
Public-Key-Pins : max-age=2592000;
pin-sha256=”HASH”;
Set-Cookie: session=HASH; Path=/; Secure; HttpOnly

各要素の説明は記載するの面倒になったので割愛します笑。気になる方はキーワードおいてますので、調べてみてください。もしくは本書にも説明があります。

ざっくりとですが、こんな感じです！色々配慮する箇所があることを理解しました。

ほんじゃーね。

タグ