『Web API デザインの鉄則』第2章読書メモ

第1章で、「Web APIをリリースするまでに決めなければならないこと」として、以下の5項目が挙げられています。

認可(Authorization)方式の決定
リソース設計
インタフェース設計
エラー表現
ドキュメント

このうち、第2章では「リソース設計」を扱っています。

リソースの定義

Web+DB Pressの記事の方ではEメールを送信するためのドメインを例に挙げてリソース設計を行っていますが、本記事ではブログの「記事(post)」をリソースとして設計してみます。

シンプルなブログ記事に必要な項目は以下のようなものになります。

タイトル
本文
状態
作成日
更新日

これを表にすると以下のようになります。人間には読みやすいですが、この表を機械に読み取らせてバリデーションさせるのは難しい。

フィールド名	名称	データ型	詳細
title	タイトル	string	記事タイトル。255文字まで。
content	本文	string	記事本文。65535文字まで。
is_public	状態	boolean	記事の状態。下書き(false)・公開(true)のいずれか。デフォルトはfalse。
created	作成日	string	記事作成日。ISO 8601形式の時刻を表す文字列。
updated	更新日	string	記事更新日。ISO 8601形式の時刻を表す文字列。

postリソースの例は以下のようになります。

{
  "title": "『Web API デザインの鉄則』第2章 読書メモ",
  "content": "「Web APIをリリースするまでに決めなければならないこと」には、以下の5項目があります。"
  "status": false,
  "created": "2014-09-05T22:51:00",
  "updated": "2014-09-05T22:53:00"
}

記事では、ここで、データを定義するためのフォーマットとしてJSON Schemaを使用しています。

公式サイトによると、JSON Schemaの特徴は以下のように紹介されています。

JSON Schema
describes your existing data format
clear, human- and machine-readable documentation
complete structural validation, useful for
automated testing
validating client-submitted data

JSON Schemaは、データのフォーマットを定義するための仕様で、人間にも機械にも読みやすい。自動テストやクライアントの送信した値のバリデーションに便利、とのこと。

{
    "title": "postリソース",
    "type": "object",
    "properties": {
        "title": {
            "title": "タイトル",
            "type": "string",
            "maxLength": 255
        },
        "content": {
            "title": "本文",
            "type": "string",
            "maxLength": 65535
        },
        "status": {
            "title": "状態",
            "type": "boolean",
            "default": false
        },
        "created": {
            "title": "作成日",
            "type": "string",
            "format": "date-time"
        },
        "updated": {
            "title": "更新日",
            "type": "string",
            "format": "date-time"
        }
    }
}

読みやすさ・書きやすさに関しては、XMLよりはマシかな程度ですね。読みやすさに関しては、JSON Schemaを表形式に変換するツール等があれば改善されそうです。書きやすさに関しても、ymlで書いてJSONに変換すればだいぶマシになるかもしれません。

JSON Schemaの最大のご利益は、このフォーマット（リソースの仕様）をそのままバリデーション等に使えることです。例えばPHPでもJSON Schemaに基づくバリデーターはいくつか実装されており、最も人気があるのはjustinrainbow/json-schemaです。

※PHPでのJSON Schemaの利用法に関しては、こちらの記事が参考になります。

『Web API デザインの鉄則』第2章読書メモ

リソースの定義

コメントをどうぞ

コメントを残すコメントをキャンセル