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. リソース定義の明文化」に関しては、インターフェース設計(後で投稿予定)で検討でも良い。