2. 表記について¶

2.1. APIパスの表記¶

BaaS REST API エンドポイント URI は以下のように定義する。

https://APIサーバホスト名/api/バージョン番号/テナントID/サービス種別

APIサーバホスト名、および "/api/" までのパスは、システム毎に異なる。
バージョン番号は、本 REST API 仕様では "1" 固定。
テナントIDは、テナントを一意に識別するテナントIDまたはテナント名
サービス種別は、REST API の種別を識別する文字列。

以下 API の説明時には、上記のうちバージョン番号より後ろのパスのみを表記する。

2.2. ACL¶

ACL は、グループ、オブジェクトストレージ(バケット、オブジェクト)、ファイルストレージ(バケット、ファイル)などに付与し、アクセス制限を行うためのものである。ACLには、対象データのオーナ、読み書き可能なユーザ・グループ、管理ユーザ・グループのリストを記述する。

ACL の表記は基本的に共通のため、ここで表記方法について説明する。

2.2.1. ACLの基本表記¶

ACL は JSON で以下のように記述する。

{
    "owner": "514af36644f9cb2eb8000001",
    "r": [ "g:authenticated" ],
    "w": [ "514af36644f9cb2eb8000002", "514af36644f9cb2eb8000003", "g:group1" ],
    "c": [ "g:group2" ],
    "u": [ "g:group2" ],
    "d": [],
    "admin": [ "514af36644f9cb2eb8000004", "g:group3" ]
}

ACL は、以下の情報から構成される。

"owner": 対象のオーナとなるユーザID
- ownerは以下 r, w, c, u, d, admin 権限を包含する(バケットに対する ACL の場合は admin 権限のみを包含する)
"r”: 対象に対する read 可能なユーザID/グループ名の一覧
"w”: 対象に対する write 可能なユーザID/グループ名の一覧。"w" は以下の属性を包含する。
- "c”: 対象に対する create(追加)可能なユーザID/グループ名の一覧 (contentACLのみ)
- "u”: 対象に対する update(更新)可能なユーザID/グループ名の一覧
- "d” 対象に対する delete(削除)可能なユーザID/グループ名の一覧
"admin”: 本ACLを変更可能なユーザID/グループ名の一覧

ACL 内でグループを記述するときは、グループ名の先頭に "g:" プレフィクスを付与する。また、以下の特殊なグループ名を定義する。

"authenticated" : ログイン認証された全ユーザを表す
"anonymous" : ログインしていないユーザを含む全ユーザを表す

2.2.2. データに対する ACL¶

ACL は JSON 形式で表記し、対象の JSON 内に埋め込む。以下にオブジェクトストレージのオブジェクトデータに埋め込む場合の例を示す。以下のように、ACL は "ACL" キー内に埋め込む。ただし、オーナとなるユーザが設定されていない場合は、owner フィールドは存在しない。

{
    "_id": "xxxxxxx",
    "itemName": "Computer 12345",
    "price": 120000,
    "date": "2014-03-04",
    "ACL": {
        "owner": "514af36644f9cb2eb8000002",
        "r": [ "g:authenticated" ],
        "w": [ "514af36644f9cb2eb8000002", "514af36644f9cb2eb8000003" ],
        "u": [],
        "d": [],
        "admin" : [ "514af36644f9cb2eb8000003" ],
    }
}

2.2.3. バケットに対する ACL 表記¶

また、対象がバケットの場合は、バケットそのものに対する ACL と、バケットの中身に対する contentACL の２つを埋め込む形となる。 contentACL には owner および admin フィールドは存在しない。また c フィールドが追加されている。

{
    "name": "BucketName",
    "ACL": {
        "owner": "514af36644f9cb2eb8000002",
        "r": [ "g:authenticated" ],
        "w": [],
        "u": [],
        "d": [],
        "admin": [ "514af36644f9cb2eb8000003" ],
    },
    "contentACL": {
        "r": [ "g:authenticated" ],
        "w": [ "514af36644f9cb2eb8000002", "514af36644f9cb2eb8000003" ],
        "c": [],
        "u": [],
        "d": []
    }
}

2.2.4. ACLに関するその他表記¶

本仕様書では、以下のような記述を用いる。

read 権限が必要 ⇒ ACL の "r" で許可されていること。
create 権限が必要 ⇒ ACL の "w" または "c" で許可されていること。
update 権限が必要 ⇒ ACL の "w" または "u" で許可されていること。
delete 権限が必要 ⇒ ACL の "w" または "d" で許可されていること。
admin 権限が必要 ⇒ ACL の "admin" で許可されていること。

なお対象がバケット以外（オブジェクトやファイルなど）の場合、対象の owner には上記権限は自動的に付与される。また対象がバケットの場合、対象の owner には admin 権限が自動的に付与される。このような場合、owner 権限については明記しない。

2.3. 仮想バケット名¶

ユーザ管理、グループ管理については、以下の２つの仮想バケットがある。

"_USERS" : ユーザの読み取り・追加・変更・削除に関するバケットコンテンツ ACL を保持する。
"_GROUPS" : グループの読み取り・追加・変更・削除に関するバケットコンテンツ ACL を保持する。

バケット管理については、以下の仮想バケットがある。

"_ROOT" : バケットの追加に関するバケットコンテンツ ACL を保持する。

2.4. その他の表記¶

'(' と ')' で囲まれた表記は、それぞれ以下のように読み替えること。

(tenantId) : テナントIDまたはテナント名。
- テナントIDは、テナント作成時に割り当てられるユニークなIDで、デベロッパーコンソール上で確認できる。
- テナントIDは、MongoDBの ObjectID の文字列表記である。これは16進数表記24文字の文字列である (例: "514af36644f9cb2eb8000002")
- テナント名は、テナント作成時に指定する文字列である。
(appId) : アプリケーションID。アプリケーション毎に割り当てられるユニークなID。
- アプリケーションIDは、アプリケーション作成時に割り当てられ、デベロッパーコンソール上で確認できる。
- テナントID同様、MongoDB の ObjectID の文字列表記である。
(appKey) : アプリケーションキー。アプリケーション毎に割り当てられる秘密キー。アプリケーションID同様、アプリケーション作成時に割り当てられ、デベロッパーコンソール上で確認できる。
(bucketName) : バケット名
- バケット名の詳細はバケット管理を参照。
(userName) : ユーザ名
- ユーザ名の詳細はユーザ管理を参照。
(groupName) : グループ名
- グループ名の詳細はグループ管理を参照。
- 以下のグループ名は予約グループ名のためグループ作成・変更・削除はできない。
  - authenticated
  - anonymous