Java
WebAPI
api
rest
REST-API

RESTful APIのリソース設計

More than 1 year has passed since last update.

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