ご挨拶
サイオステクノロジーの紀之定と申すものです。今年から新卒で入社いたしました。これからちょくちょくブログを書いていくつもりなので何卒よろしくお願いいたします。
ただいま絶賛研修を受けている最中でございましてその過程で Rest API について学習する機会があったのでその忘備録としてこのブログにまとめていきたいと思います。
本題
Rest 原則とは何ぞや
Rest というのは設計思想の名前です。そして Rest で設計する際のお約束事みたいなものが「Rest 原則」という訳です！では早速 Rest 原則の中身を見ていきましょう。
- クライアント/サーバー
- ステートレス
- キャッシュ制御
- 統一インターフェース
- 階層化システム
- コードオンデマンド
クライアント/サーバー
Web アプリをやっている人ならば誰もが見る構成のやつです。 クライアントの「〇〇したいです！」という様々な要求にサーバーが「了解！→ 実行中 → 実行終わったよ！」の順に処理していくシステム構成のことです！
ステートレス
各通信ごとで情報が完結している状態を表します。逆を言えば前の通信の情報は考慮されないということになります。少し難しい気がする（主観）ので具体例を挙げます！
ステートフル
ステートレス
こんな感じでステートレスなやり取りは私たちが普段使うステートフルなやり取りと比べて手間がかかりますが、その代わりに発言単体で内容が理解できるようになっています！
キャッシュ制御
これは簡単で無駄な通信を減らすためにクライアントがレスポンスをキャッシュできるようにしましょうってことです。
統一インターフェース
これは人による API の表現方法の差異をなるべく減らすために用意された 4 つの制約を意味しています。 具体的には以下のものになります。
- リソースの識別
- 表現を用いたリソース操作
- 自己記述メッセージ
- アプリケーション状態エンジンとしてのハイパーメディア（HATEOS）
リソースの識別
URI を用いてサーバーに保存されたデータを識別できることを意味します。 例えばユーザー情報を取得するための URI は 「http://example.com/users」 といった分かりやすい URI にする必要があります！
表現を用いたリソース操作
簡単にいうとリクエストを送る際に表現（認証情報などの追加情報）を付与してサーバー側にリソースの編集をお願いすることを指します。他にも表現の種類は数多くあります！
自己記述メッセージ
メッセージ内容が何であるか、ヘッダーに記述されている必要があります！
Content-Type: text/plain; charset=utf-8
的なやつです。
アプリケーション状態エンジンとしてのハイパーメディア（HATEOS）
レスポンスに現在の状態と関連するハイパーリンクが含まれている。 例をあげると検索結果の前ページ、次ページのリンクが挙げられます。
{
"message": "太郎の友人一覧（3ページ目）",
"links": [
{ "name": "prev", "url": "<http://sample.com/users/taro/friends/2>" },
{ "name": "next", "url": "<http://sample.com/users/taro/friends/4>" }
]
}
階層化システム
各システムに役割を決めて独立させることによって保守性、再利用性の向上を狙えます。 例えば、「Web サーバー」、「DB サーバー」を分割して配置する等が挙げられます。
コードオンデマンド
クライアント側がコードをダウンロードして実行できる状態を指します。 例としては「html ファイルの取得」等が挙げられます。
Rest API の仕様書を作ってみるの会
上述した内容を踏まえて openapi の書式に則って簡単な Rest API の仕様書を作ってみました！
openapi: 3.0.0
info:
title: "test"
version: 1.0.0
tags:
- name: users
paths:
"/users":
post:
tags:
- "users"
summary: "ユーザー登録"
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: "sios@sample.com"
name:
type: string
example: "sios"
age:
type: integer
example: 22
responses:
"201":
description: "success"
"/users/{id}":
get:
tags:
- "users"
summary: "ユーザー取得"
parameters:
- name: "id"
in: path
required: true
schema:
type: string
example: "sample@sios.com"
responses:
"200":
description: "success"
content:
application/json:
schema:
type: object
properties:
name:
type: string
example: "sios"
age:
type: integer
example: 22
openapi について説明してしまうと本題から反れてしまうため今回触れることはしません。上述の api 仕様書は rest 原則に沿って書かれた部分もありますが考慮していない部分もあります。 例えば「ステートレス」については get, post どちらも responses オブジェクトのみを見たとき何についてのデータを返却しているか説明されていません。どちらかというと「ステートフル」になっていると言えます。
まとめ
今回は rest 原則とはなんぞやとのことでしたがつまるところただの「考え方」に過ぎないものでした。 rest 原則は今から 20 年ほど前に発案されたいわば古い考え方なのでその全てが現代の api 仕様書に適用されているとは限りません。 では api 仕様書を実際にどのように書けば良いかと疑問に思った方は「openapi」について学習してみてください！
アイキャッチ画像：著作者：storyset／出典：Freepik
