RESTful APIのリソース設計

RESTful APIの設計を行う上で、まずはリソース設計を行う。リソース設計では以下を検討する。

1. 何をリソースとするか

とにもかくにも何をリソースとするかを決める必要がある。APIの利用者がどのようなリソースを必要としているか、そのリソースをどのように利用するか、といったユースケースを考えながらリソースを抽出する。

2. リソースに対するCRUD操作

抽出したリソースに対して、どのようなCRUD操作が必要かを検討する。なお、CRUD操作に関しては「RESTful APIとは何なのか」のRESTの原則 - 統一インターフェースでも述べた通り、HTTPの標準メソッドを利用する。

3. リソース間の従属関係(親子関係)

それらのリソース間でどのような従属関係があるかを検討する。例えば、会社には部署があり部署には部員が所属する、といったようなイメージ。

4. リソースの各項目のデータ型の定義

リソースの各項目のデータ型を定義する(String、boolean、Number等)。

5. リソース定義の明文化

API利用者、API開発者のために、リソース定義を明文化する。ちなみに、明文化するにあたり、

項目名	名称	データ型	詳細
firstName	名	String	-
lastName	姓	String	-
age	年齢	String	-

のような感じで明文化しても良いが、JSON Schemaを利用することで以下のメリットを得られる。

• 既存のデータ型を記述できる
• 人にも機械にも読める文書になる
• 完全に構造化されたデータの検証ができる

そのため、明文化にはJSON Schemaを利用した方が良いかもしれない。
※http://json-schema.org/examples.html のサンプルを拝借

{
    "title": "Example Schema",
    "type": "object",
    "properties": {
        "firstName": {
            "type": "string"
        },
        "lastName": {
            "type": "string"
        },
        "age": {
            "description": "Age in years",
            "type": "integer",
            "minimum": 0
        }
    },
    "required": ["firstName", "lastName"]
}

留意したいこと

リソース設計 = DBのER設計ではないということ(DBのER設計とは切り離して考えたほうが良い)。また、「4. リソースの各項目のデータ型の定義」と「5. リソース定義の明文化」に関しては、インターフェース設計(後で投稿予定)で検討でも良い。

参考

RESTful Webサービス
Web API: The Good Parts