[A-00207] API設計・実装入門

APIについて深く考える為の記事です。基本的には入門用の記事を目指して書いておりますが、用語などは知っている前提で記載するので適宜調べていただければと思います。

・RestAPIの設計について

APIの代表例のRestAPIの設計について考える

とりあえずルール的なところ、常識的なところについて押さえておく

他社のAPI-Endpointのサンプルは下記の通り

社名	method	Endpoint
X(Twitter)	GET	https://api.twitter.com/2/tweets/search/all
X(Twitter)	GET	https://api.twitter.com/2/users/by/username/USER_NAME
X(Twitter)	GET	https://api.twitter.com/2/users/USER_ID/tweets
OpenWeatherMap	GET	https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}
OpenWeatherMap	GET	https://pro.openweathermap.org/data/2.5/forecast/climate?lat={lat}&lon={lon}

リソースに対する思想です。基本的にこの思想を元にAPIを作成します。

リソースは必ずURIを持つ
RestAPIを提供するアプリケーションにはアドレス可能性がなくてはならない(URIを通じて簡単にリソースに辿り着ける事)
ステートレスでなくてはならない(全てのHTTPリクエストは完全に独立している。リクエストAを実行したのちにリクエストBを実行すると、リクエストBを最初に実行した時と振る舞いが変わる、ということになってはならない)
冪等性を備えなくてはならない
リソース状態、アプリケーション状態の二つがある
接続性を持たせる(リソースは他のリソースへのリンクを持たせることができる)

RestAPIにおけるHTTPメソッドは下記のようなものがある

HTTPメソッド	リクエスト	レスポンス	操作
GET	パスパラメータ or クエリパラメータ	レスポンスボディで返却	リソースの取得
PUT	リクエストボディ, パスパラメータ	空のレスポンスボディ	リソース(全体)の更新、作成
PATCH	リクエストボディ,パスパラメータ	空のレスポンスボディ	リソース(部分)の更新
POST	リクエストボディ	レスポンスボディ	リソースの作成
DELETE		レスポンスボディにメッセージ付きで返却	リソースの削除
HEAD			リソースのメタデータの取得
OPTIONS			リソースがサポートするメソッドの参照

RestAPIサーバーからクライアントへ返すHTTPステータスコードについて記載する。

ステータスコード	Method	Success/Error	説明
200 OK	GET,POST,PUT,DELETE	成功(Success)	リクエストが成功して正常なレスポンスがクライアントに返却された場合に使用
201 Created	POST	成功(Success)	リクエストが成功して新しいリソースが作成された場合に使用