Help us understand the problem. What is going on with this article?

RESTful APIのリソース設計

More than 3 years have 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

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away