バケツAPI (Version 1)

バケツ関連の操作を提供するAPI。

サーバ:

frugalosプロセスのこと
各サーバは、クラスタ内で一意なIDを有している

バケツ:

バケツとは、オブジェクト群を格納するための入れ物
オブジェクトの名前空間は、バケツ毎に異なる
冗長化方式等の設定は、バケツ毎に異なるものを設定可能
バケツ内の領域は、作成時に指定された数のセグメントに(論理的に)分割されている
一つのバケツには、一つのデバイスが対応する
- オブジェクト群は、そのデバイスに格納される
- デバイスに関する詳細はデバイスAPI を参照のこと
なお__systemという名前のバケツが、システム用に予約されている(i.e., 最初から存在し削除は不可)

セグメント:

バケツの論理的な分割単位
セグメント数は、バケツ作成時に指定されて、その後変更は不可
一つのバケツは、典型的には千個程度のセグメントに分割される
オブジェクト一覧を取得したい場合を除いて、基本的には利用者が意識する必要はない

オブジェクト:

オブジェクトとは、IDとそれに対応する内容、およびバージョンから構成されるデータ
あるオブジェクトは、いずれかのバケツに格納され、そのIDはバケツ内で一意である
あるオブジェクトのバージョンは、保存(PUT)毎に自動で割り当てられ、その値は単調増加することが保証されている
- 値が1ずつ増加する保証はない
- このバージョンの値を利用することで、いわゆるCAS(Compare And Swap)的な操作が可能となる
オブジェクトの内容としては、任意のバイト列を格納可能
- ただし、構成・設定に応じて、最大サイズには上限が設けられる
- 具体的な上限は設定に依存するが、通常は数十MB程度となる
- TODO: 使用しているバケツでの上限は TODO のAPIを叩くことで取得可能

オブジェクトプレフィックス:

バケツに登録されているオブジェクトに付与されているIDの接頭辞
接頭辞であるので、あるオブジェクトに対してオブジェクトプレフィックスは複数存在する
- 例えば lv12 のオブジェクトプレフィックスは l, lv, lv1, lv12 となる

デッドライン:

オブジェクト関連の操作では、その完了までに要する時間の期待上限値が指定可能である
- この値のことをデッドラインと呼称する
デッドラインが指定された操作は、極力その時間内で実行が完了するようにスケジューリングされる
ただし、その時間内で確実に完了する保証はなく、またそれを超過したからといって実行が中断されることもない
- つまり一種の優先度的な値
即時に実行する必要がない操作に関しては、デッドラインを長めに指定することで、他のより緊急度の高い操作を優先されることが可能

デバイス:

オブジェクト群の物理的な格納先
デバイスには大別して 物理デバイス と 仮想デバイス の二種類が存在する
物理デバイス:
- HDDやSSD等の物理的なデバイス
- 各物理デバイスは、特定の サーバ に属する
- 物理デバイスの種別は、その実体に応じてmemoryやmonofileといったようにさらに細分化される
仮想デバイス (type=virtual):
- 物理デバイスをグルーピングする仮想的なデバイス
- 「マシン」、「ラック」、「データセンタ」といった単位は仮想デバイスを用いて表現する
type=memory:
- 全てのオブジェクトをメモリ上に保持する
type=monofile:
- オブジェクト群を単一ファイル上に保持する
サーバが保持するオブジェクト群を物理的に保持するための装置
- e.g., HDD, SSD
各サーバへのデバイスの追加はデバイスAPI経由で行う

重み (Weight):

デバイスをセグメントに割り当てる際の重み
各デバイスは、この値に比例した数のセグメントを担当することになる
デフォルト値は、デバイスの種別によって異なる:
- memory: 1
- monofile: capacity_gbの値
- virtual: childrenの重みの合計値

デバイスの無効化:

enableフラグをfalseに設定することで、一時的にそのデバイスの使用を停止することができる
これは機能的にはデバイスの削除と似ているが、以下の点が異なる:
- デバイスが無効化された場合には、そのデバイスが担当していたセグメント群のみを、他のデバイス群が肩代わりする
  - つまり、データの移動は発生するが、その量は最小限で済む
  - => 短期的に取り外しているだけなら、こちらの方が良い
- 逆に、デバイスを削除した場合には、クラスタ全体でのセグメント群の割り当てが最適化されるように割振りの調整が行われる
  - つまり、データの移動量は若干増えるが、それが完了した後のバランスぐらいは最適なものとなる
  - => 永続的に削除するなら、こちらの方が良い

エラー時の応答:

エラー時の応答形式はRFC 7807に準拠する
各エンドポイントで固有の意味を持つ応答ステータスコードに関しては、この文書内で明示的に定義している
それ以外のエラー応答に関しては、HTTPの一般的なセマンティクスに従い、この文書内で定義することはしない
- e.g., 応答ステータスが500なら、サーバ内部エラー

バケツ ¶

バケツ一覧 ¶

バケツ一覧の取得
GET`/v1/buckets`

存在するバケツのID一覧を返す。

Example URI

GET http://example.com/v1/buckets

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": "chunk",
    "device": "device00",
    "type": "Hello, world!"
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "バケツのID"
      },
      "device": {
        "type": "string",
        "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
      },
      "type": {
        "type": "string",
        "enum": [
          "dispersed",
          "replicated",
          "metadata",
          "dispersed"
        ],
        "description": "バケツ内のデータの冗長化方式"
      }
    },
    "required": [
      "id",
      "device",
      "type"
    ]
  }
}

バケツ操作 ¶

バケツ構成の取得
GET`/v1/buckets/{bucket_id}`

指定されたバケツの構成を取得する。

Example URI

GET http://example.com/v1/buckets/foo

URI Parameters

HideShow

bucket_id: string (required) Example: foo
操作対象のバケツのID

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "dispersed": {
    "data_fragment_count": 1,
    "id": "chunk",
    "device": "device00",
    "seqno": 0,
    "segment_count": 1000,
    "tolerable_faults": 3
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {},
  "oneOf": [
    {
      "properties": {
        "dispersed": {
          "type": "object",
          "properties": {
            "data_fragment_count": {
              "type": "number",
              "description": "ErasureCodingにおけるデータフラグメントの数(正の整数)"
            },
            "id": {
              "type": "string",
              "description": "バケツのID"
            },
            "device": {
              "type": "string",
              "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
            },
            "seqno": {
              "type": "number",
              "description": "バケツ内部で自動採番されている数値。利用者が意識する必要はない。"
            },
            "segment_count": {
              "type": "number",
              "description": "セグメント数 (正の整数)",
              "default": 1000
            },
            "tolerable_faults": {
              "type": "number",
              "description": "故障耐性数 (非負の整数)"
            }
          },
          "required": [
            "data_fragment_count",
            "id",
            "device",
            "seqno",
            "tolerable_faults"
          ]
        }
      }
    },
    {
      "properties": {
        "replicated": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "バケツのID"
            },
            "device": {
              "type": "string",
              "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
            },
            "seqno": {
              "type": "number",
              "description": "バケツ内部で自動採番されている数値。利用者が意識する必要はない。"
            },
            "segment_count": {
              "type": "number",
              "description": "セグメント数 (正の整数)",
              "default": 1000
            },
            "tolerable_faults": {
              "type": "number",
              "description": "故障耐性数 (非負の整数)"
            }
          },
          "required": [
            "id",
            "device",
            "seqno",
            "tolerable_faults"
          ]
        }
      }
    },
    {
      "properties": {
        "metadata": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "バケツのID"
            },
            "device": {
              "type": "string",
              "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
            },
            "seqno": {
              "type": "number",
              "description": "バケツ内部で自動採番されている数値。利用者が意識する必要はない。"
            },
            "segment_count": {
              "type": "number",
              "description": "セグメント数 (正の整数)",
              "default": 1000
            },
            "tolerable_faults": {
              "type": "number",
              "description": "故障耐性数 (非負の整数)"
            }
          },
          "required": [
            "id",
            "device",
            "seqno",
            "tolerable_faults"
          ]
        }
      }
    }
  ]
}

Response 404

HideShow

指定されたバケツが存在しない。

Headers

Content-Type: application/problem+json

Body

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

バケツの作成・更新
PUT`/v1/buckets/{bucket_id}`

バケツの新規作成、あるいは更新を行う。

Example URI

PUT http://example.com/v1/buckets/foo

URI Parameters

HideShow

bucket_id: string (required) Example: foo
操作対象のバケツのID

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "dispersed": {
    "data_fragment_count": 1,
    "id": "chunk",
    "device": "device00",
    "seqno": 0,
    "segment_count": 1000,
    "tolerable_faults": 3
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {},
  "oneOf": [
    {
      "properties": {
        "dispersed": {
          "type": "object",
          "properties": {
            "data_fragment_count": {
              "type": "number",
              "description": "ErasureCodingにおけるデータフラグメントの数(正の整数)"
            },
            "id": {
              "type": "string",
              "description": "バケツのID"
            },
            "device": {
              "type": "string",
              "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
            },
            "seqno": {
              "type": "number",
              "description": "バケツ内部で自動採番されている数値。利用者が意識する必要はない。"
            },
            "segment_count": {
              "type": "number",
              "description": "セグメント数 (正の整数)",
              "default": 1000
            },
            "tolerable_faults": {
              "type": "number",
              "description": "故障耐性数 (非負の整数)"
            }
          },
          "required": [
            "data_fragment_count",
            "id",
            "device",
            "seqno",
            "tolerable_faults"
          ]
        }
      }
    },
    {
      "properties": {
        "replicated": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "バケツのID"
            },
            "device": {
              "type": "string",
              "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
            },
            "seqno": {
              "type": "number",
              "description": "バケツ内部で自動採番されている数値。利用者が意識する必要はない。"
            },
            "segment_count": {
              "type": "number",
              "description": "セグメント数 (正の整数)",
              "default": 1000
            },
            "tolerable_faults": {
              "type": "number",
              "description": "故障耐性数 (非負の整数)"
            }
          },
          "required": [
            "id",
            "device",
            "seqno",
            "tolerable_faults"
          ]
        }
      }
    },
    {
      "properties": {
        "metadata": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "バケツのID"
            },
            "device": {
              "type": "string",
              "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
            },
            "seqno": {
              "type": "number",
              "description": "バケツ内部で自動採番されている数値。利用者が意識する必要はない。"
            },
            "segment_count": {
              "type": "number",
              "description": "セグメント数 (正の整数)",
              "default": 1000
            },
            "tolerable_faults": {
              "type": "number",
              "description": "故障耐性数 (非負の整数)"
            }
          },
          "required": [
            "id",
            "device",
            "seqno",
            "tolerable_faults"
          ]
        }
      }
    }
  ]
}

Response 200

HideShow

バケツが更新された。

Headers

Content-Type: application/json

Body

{
  "dispersed": {
    "data_fragment_count": 1,
    "id": "chunk",
    "device": "device00",
    "seqno": 0,
    "segment_count": 1000,
    "tolerable_faults": 3
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {},
  "oneOf": [
    {
      "properties": {
        "dispersed": {
          "type": "object",
          "properties": {
            "data_fragment_count": {
              "type": "number",
              "description": "ErasureCodingにおけるデータフラグメントの数(正の整数)"
            },
            "id": {
              "type": "string",
              "description": "バケツのID"
            },
            "device": {
              "type": "string",
              "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
            },
            "seqno": {
              "type": "number",
              "description": "バケツ内部で自動採番されている数値。利用者が意識する必要はない。"
            },
            "segment_count": {
              "type": "number",
              "description": "セグメント数 (正の整数)",
              "default": 1000
            },
            "tolerable_faults": {
              "type": "number",
              "description": "故障耐性数 (非負の整数)"
            }
          },
          "required": [
            "data_fragment_count",
            "id",
            "device",
            "seqno",
            "tolerable_faults"
          ]
        }
      }
    },
    {
      "properties": {
        "replicated": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "バケツのID"
            },
            "device": {
              "type": "string",
              "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
            },
            "seqno": {
              "type": "number",
              "description": "バケツ内部で自動採番されている数値。利用者が意識する必要はない。"
            },
            "segment_count": {
              "type": "number",
              "description": "セグメント数 (正の整数)",
              "default": 1000
            },
            "tolerable_faults": {
              "type": "number",
              "description": "故障耐性数 (非負の整数)"
            }
          },
          "required": [
            "id",
            "device",
            "seqno",
            "tolerable_faults"
          ]
        }
      }
    },
    {
      "properties": {
        "metadata": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "バケツのID"
            },
            "device": {
              "type": "string",
              "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
            },
            "seqno": {
              "type": "number",
              "description": "バケツ内部で自動採番されている数値。利用者が意識する必要はない。"
            },
            "segment_count": {
              "type": "number",
              "description": "セグメント数 (正の整数)",
              "default": 1000
            },
            "tolerable_faults": {
              "type": "number",
              "description": "故障耐性数 (非負の整数)"
            }
          },
          "required": [
            "id",
            "device",
            "seqno",
            "tolerable_faults"
          ]
        }
      }
    }
  ]
}

Response 201

HideShow

バケツが作成された。

Headers

Content-Type: application/json

Body

{
  "dispersed": {
    "data_fragment_count": 1,
    "id": "chunk",
    "device": "device00",
    "seqno": 0,
    "segment_count": 1000,
    "tolerable_faults": 3
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {},
  "oneOf": [
    {
      "properties": {
        "dispersed": {
          "type": "object",
          "properties": {
            "data_fragment_count": {
              "type": "number",
              "description": "ErasureCodingにおけるデータフラグメントの数(正の整数)"
            },
            "id": {
              "type": "string",
              "description": "バケツのID"
            },
            "device": {
              "type": "string",
              "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
            },
            "seqno": {
              "type": "number",
              "description": "バケツ内部で自動採番されている数値。利用者が意識する必要はない。"
            },
            "segment_count": {
              "type": "number",
              "description": "セグメント数 (正の整数)",
              "default": 1000
            },
            "tolerable_faults": {
              "type": "number",
              "description": "故障耐性数 (非負の整数)"
            }
          },
          "required": [
            "data_fragment_count",
            "id",
            "device",
            "seqno",
            "tolerable_faults"
          ]
        }
      }
    },
    {
      "properties": {
        "replicated": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "バケツのID"
            },
            "device": {
              "type": "string",
              "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
            },
            "seqno": {
              "type": "number",
              "description": "バケツ内部で自動採番されている数値。利用者が意識する必要はない。"
            },
            "segment_count": {
              "type": "number",
              "description": "セグメント数 (正の整数)",
              "default": 1000
            },
            "tolerable_faults": {
              "type": "number",
              "description": "故障耐性数 (非負の整数)"
            }
          },
          "required": [
            "id",
            "device",
            "seqno",
            "tolerable_faults"
          ]
        }
      }
    },
    {
      "properties": {
        "metadata": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string",
              "description": "バケツのID"
            },
            "device": {
              "type": "string",
              "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
            },
            "seqno": {
              "type": "number",
              "description": "バケツ内部で自動採番されている数値。利用者が意識する必要はない。"
            },
            "segment_count": {
              "type": "number",
              "description": "セグメント数 (正の整数)",
              "default": 1000
            },
            "tolerable_faults": {
              "type": "number",
              "description": "故障耐性数 (非負の整数)"
            }
          },
          "required": [
            "id",
            "device",
            "seqno",
            "tolerable_faults"
          ]
        }
      }
    }
  ]
}

Response 400

HideShow

指定されたバケツの構成が不正だったり、対象のバケツが更新をサポートしていない場合に返される。なお、更新をサポートしているのは、種別がmetadataのバケツのみである。

Headers

Content-Type: application/problem+json

Body

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

バケツの削除（未実装）
DELETE`/v1/buckets/{bucket_id}`

指定されたバケツを削除する。

Example URI

DELETE http://example.com/v1/buckets/foo

URI Parameters

HideShow

bucket_id: string (required) Example: foo
操作対象のバケツのID

Response 200

HideShow

削除されたバケツの構成を返す。

Headers

Content-Type: application/json

Body

{
  "id": "chunk",
  "device": "device00",
  "seqno": 0,
  "segment_count": 1000,
  "tolerable_faults": 3
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "バケツのID"
    },
    "device": {
      "type": "string",
      "description": "バケツの中身(オブジェクト群)を保存するのに使用するデバイスのID"
    },
    "seqno": {
      "type": "number",
      "description": "バケツ内部で自動採番されている数値。利用者が意識する必要はない。"
    },
    "segment_count": {
      "type": "number",
      "description": "セグメント数 (正の整数)",
      "default": 1000
    },
    "tolerable_faults": {
      "type": "number",
      "description": "故障耐性数 (非負の整数)"
    }
  },
  "required": [
    "id",
    "device",
    "seqno",
    "tolerable_faults"
  ]
}

オブジェクト ¶

オブジェクト操作 ¶

個々のオブジェクトに対する操作。HTTP ヘッダーで If-None, If-None-Match のいずれも指定しなかった場合はオブジェクトのバージョン確認はされない。

指定可能な HTTP Header は以下のとおり。

If-None
- オブジェクトのバージョンがこのヘッダーで指定した値の場合のみ操作が適用される。
- * を指定すると任意のバージョンに対して操作が適用される。
If-None-Match
- オブジェクトのバージョンがこのヘッダーで指定した値以外の場合のみ操作が適用される。
- * を指定するとオブジェクトが存在しない場合のみ操作が適用される。

オブジェクトの取得
GET`/v1/buckets/{bucket_id}/objects/{object_id}{?deadline,consistency,subset}`

object_idで指定されたオブジェクトの内容を取得する。

Example URI

GET http://example.com/v1/buckets/foo/objects/bar?deadline=5000&consistency=consistent&subset=2

URI Parameters

HideShow

bucket_id: string (required) Example: foo
操作対象のバケツのID
object_id: string (required) Example: bar
操作対象のオブジェクトのID
deadline: number (optional) Default: 5000 Example: 5000
処理完了までのデッドライン(ミリ秒)
consistency: string (optional) Default: consistent Example: consistent
オブジェクト取得時の整合性の指定。consistent, quorum, stale, subset のいずれかを指定する。
subset: number (required) Example: 2
整合性の指定に subset を指定した時にいくつの MDS ノードからオブジェクト取得を試みるかを指定する。

Response 200

HideShow

以前にPUTされたオブジェクトの内容を取得する。

応答ヘッダのETagには、該当オブジェクトのバージョンが格納される。

Headers

Content-Type: application/octet-stream
ETag: 10

Body

${オブジェクトの内容}

Response 404

HideShow

対象オブジェクトが存在しない。

Headers

Content-Type: application/problem+json

Body

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

Response 410

HideShow

object_idに対応するオブジェクトは存在するが、内容が壊れている。

再び利用可能にするには、ユーザが再度PUTを発行する必要がある可能性が高い。

応答ヘッダのETagには、該当オブジェクトのバージョンが格納される。

Headers

Content-Type: application/problem+json
ETag: 10

Body

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

オブジェクトの存在確認
HEAD`/v1/buckets/{bucket_id}/objects/{object_id}{?deadline,consistency,subset}`

object_idで指定されたオブジェクトが存在するかを確認する。

Example URI

HEAD http://example.com/v1/buckets/foo/objects/bar?deadline=5000&consistency=consistent&subset=2

URI Parameters

HideShow

bucket_id: string (required) Example: foo
操作対象のバケツのID
object_id: string (required) Example: bar
操作対象のオブジェクトのID
deadline: number (optional) Default: 5000 Example: 5000
処理完了までのデッドライン(ミリ秒)
consistency: string (optional) Default: consistent Example: consistent
オブジェクト取得時の整合性の指定。consistent, quorum, stale, subset のいずれかを指定する。
subset: number (required) Example: 2
整合性の指定に subset を指定した時にいくつの MDS ノードからオブジェクト取得を試みるかを指定する。

Response 200

HideShow

応答ヘッダのETagには、該当オブジェクトのバージョンが格納される。

Headers

Content-Type: application/octet-stream
ETag: 10

Response 404

HideShow

対象オブジェクトが存在しない。

Headers

Content-Type: application/problem+json

Body

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

オブジェクトの作成・更新
PUT`/v1/buckets/{bucket_id}/objects/{object_id}{?deadline}`

オブジェクトの新規作成、あるいは更新を行う。

Example URI

PUT http://example.com/v1/buckets/foo/objects/bar?deadline=5000

URI Parameters

HideShow

bucket_id: string (required) Example: foo
操作対象のバケツのID
object_id: string (required) Example: bar
操作対象のオブジェクトのID
deadline: number (optional) Default: 5000 Example: 5000
処理完了までのデッドライン(ミリ秒)

Request

HideShow

Headers

Content-Type: application/octet-stream

Body

${オブジェクトの内容}

Response 200

HideShow

オブジェクトが更新された。

応答ヘッダのETagには、更新後のオブジェクトのバージョンが格納される。

Headers

ETag: 10

Response 201

HideShow

オブジェクトが作成された。

応答ヘッダのETagには、作成後のオブジェクトのバージョンが格納される。

Headers

ETag: 10

Response 412

HideShow

expectパラメータで指定された条件と、実際のオブジェクトのバージョンが異なる。

応答ヘッダのETagには、現在のオブジェクトのバージョンが格納される。なお、オブジェクトが存在しない場合には、このヘッダは応答には含まれない。

Headers

Content-Type: application/problem+json
ETag: 10

Body

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

オブジェクトの削除
DELETE`/v1/buckets/{bucket_id}/objects/{object_id}{?deadline}`

オブジェクトの削除を行う。

対象オブジェクトが存在しない場合には、404応答が返される。

Example URI

DELETE http://example.com/v1/buckets/foo/objects/bar?deadline=5000

URI Parameters

HideShow

bucket_id: string (required) Example: foo
操作対象のバケツのID
object_id: string (required) Example: bar
操作対象のオブジェクトのID
deadline: number (optional) Default: 5000 Example: 5000
処理完了までのデッドライン(ミリ秒)

Response 200

HideShow

オブジェクトが削除された。

応答ヘッダのETagには、削除されたオブジェクトのバージョンが格納される。

Headers

ETag: 10

Response 404

HideShow

対象オブジェクトが存在しない。

Headers

Content-Type: application/problem+json

Body

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

Response 412

HideShow

expectパラメータで指定された条件と、実際のオブジェクトのバージョンが異なる。

Headers

Content-Type: application/problem+json
ETag: 10

Body

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

オブジェクトプレフィックス ¶

プレフィックス指定でのオブジェクト操作 ¶

オブジェクトの削除
DELETE`/v1/buckets/{bucket_id}/object_prefixes/{object_prefix}`

指定したプレフィックスを ID のプレフィックスに持つオブジェクトを削除する。

例えば、lv123, 25lv25 の ID を持つオブジェクトが登録されている場合に、lv を object_prefix に指定すると、lv123 のみ削除される。

削除されたオブジェクトが1つもなくても 200 応答が返される。

Example URI

DELETE http://example.com/v1/buckets/live/object_prefixes/lv3293

URI Parameters

HideShow

bucket_id: string (required) Example: live
操作対象のバケツのID
object_prefix: string (required) Example: lv3293
削除対象のオブジェクトのIDのプレフィックス

Response 200

HideShow

オブジェクトが削除された。

Body

{
  "total": "Hello, world!"
}

Schema

{
  "type": "object",
  "properties": {
    "total": {
      "type": "string",
      "description": "削除されたオブジェクト総数の文字列表現(JSON で表現できない巨大な数になりうるため)"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}

セグメント ¶

セグメント一覧 ¶

セグメント一覧の取得
GET`/v1/buckets/{bucket_id}/segments`

指定されたバケツのセグメント一覧を取得する。

Example URI

GET http://example.com/v1/buckets/foo/segments

URI Parameters

HideShow

bucket_id: string (required) Example: foo
操作対象のバケツのID

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": 0
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "number",
        "description": "セグメントのID"
      }
    },
    "required": [
      "id"
    ]
  }
}

Response 404

HideShow

対象のバケツが存在しない。

Headers

Content-Type: application/problem+json

Body

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

セグメント操作 ¶

セグメント構成の取得(未実装)
GET`/v1/buckets/{bucket_id}/segments/{segment_id}`

指定されたセグメントの構成情報を返す。

TODO: 各デバイスに関して、データ同期が完了(i.e., 即座に利用可能か)しているかどうかのフラグを返しても良いかも (statistics的なもので「Raftログのcommit済み地点」を返せば十分？)

応答の値は暫定。

Example URI

GET http://example.com/v1/buckets/foo/segments/0

URI Parameters

HideShow

bucket_id: string (required) Example: foo
操作対象のバケツのID
segment_id: number (required) Example: 0
操作対象のセグメントのID

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "devices": [
    "device00",
    "device01"
  ]
}

オブジェクト一覧 ¶

オブジェクト一覧の取得
GET`/v1/buckets/{bucket_id}/segments/{segment_id}/objects`

指定されたセグメントに属するオブジェクトの一覧を返す。

Example URI

GET http://example.com/v1/buckets/foo/segments/0/objects

URI Parameters

HideShow

bucket_id: string (required) Example: foo
操作対象のバケツのID
segment_id: number (required) Example: 0
操作対象のセグメントのID

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
  {
    "id": "sm9",
    "version": 3
  }
]

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "オブジェクトのID"
      },
      "version": {
        "type": "number",
        "description": "オブジェクトのバージョン"
      }
    },
    "required": [
      "id",
      "version"
    ]
  }
}

Response 400

HideShow

セグメントIDが不正。セグメントIDに適切な型を指定しているか確認する。

Headers

Content-Type: application/problem+json

Body

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

Response 404

HideShow

対象のセグメントが存在しない。存在しないバケツIDが指定された場合に返される。

Headers

Content-Type: application/problem+json

Body

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

Response 500

HideShow

バケツは存在するがセグメントIDが存在するセグメント範囲を超えている。現在は実装の都合で 500 を返すが、将来的には 400 を返すように修正される予定。

Headers

Content-Type: application/problem+json

Body

{
  "kind": "Other",
  "cause": "Not Found",
  "history": [
    null
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "description": "エラーの種類を表す文字列"
    },
    "cause": {
      "type": "string",
      "description": "エラーを発生させた原因の説明"
    },
    "history": {
      "type": "array",
      "description": "エラーが発生するまでに経由したコード上の経路情報。デバッグ用の情報。"
    }
  },
  "required": [
    "kind",
    "cause",
    "history"
  ]
}

用語 ¶

共通仕様 ¶

バケツ ¶

バケツ一覧 ¶

バケツ一覧の取得GET/v1/buckets

Example URI

Headers

Body

Schema

バケツ操作 ¶

バケツ構成の取得GET/v1/buckets/{bucket_id}

Example URI

Headers

Body

Schema

Headers

Body

Schema

バケツの作成・更新PUT/v1/buckets/{bucket_id}

Example URI

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

バケツの削除（未実装）DELETE/v1/buckets/{bucket_id}

Example URI

Headers

Body

Schema

オブジェクト ¶

オブジェクト操作 ¶

オブジェクトの取得GET/v1/buckets/{bucket_id}/objects/{object_id}{?deadline,consistency,subset}

注記 ¶

Example URI

Headers

Body

Headers

Body

Schema

Headers

Body

Schema

オブジェクトの存在確認HEAD/v1/buckets/{bucket_id}/objects/{object_id}{?deadline,consistency,subset}

注記 ¶

Example URI

Headers

Headers

Body

Schema

オブジェクトの作成・更新PUT/v1/buckets/{bucket_id}/objects/{object_id}{?deadline}

Example URI

Headers

Body

Headers

Headers

Headers

Body

Schema

オブジェクトの削除DELETE/v1/buckets/{bucket_id}/objects/{object_id}{?deadline}

Example URI

Headers

Headers

Body

Schema

Headers

Body

Schema

オブジェクトプレフィックス ¶

プレフィックス指定でのオブジェクト操作 ¶

オブジェクトの削除DELETE/v1/buckets/{bucket_id}/object_prefixes/{object_prefix}

Example URI

Body

用語

共通仕様

バケツ一覧の取得
GET`/v1/buckets`

バケツ構成の取得
GET`/v1/buckets/{bucket_id}`

バケツの作成・更新
PUT`/v1/buckets/{bucket_id}`

バケツの削除（未実装）
DELETE`/v1/buckets/{bucket_id}`

オブジェクトの取得
GET`/v1/buckets/{bucket_id}/objects/{object_id}{?deadline,consistency,subset}`

注記

オブジェクトの存在確認
HEAD`/v1/buckets/{bucket_id}/objects/{object_id}{?deadline,consistency,subset}`

注記

オブジェクトの作成・更新
PUT`/v1/buckets/{bucket_id}/objects/{object_id}{?deadline}`

オブジェクトの削除
DELETE`/v1/buckets/{bucket_id}/objects/{object_id}{?deadline}`

オブジェクトの削除
DELETE`/v1/buckets/{bucket_id}/object_prefixes/{object_prefix}`

セグメント一覧の取得
GET`/v1/buckets/{bucket_id}/segments`

セグメント構成の取得(未実装)
GET`/v1/buckets/{bucket_id}/segments/{segment_id}`

注記

オブジェクト一覧の取得
GET`/v1/buckets/{bucket_id}/segments/{segment_id}/objects`