バケツAPI (Version 1)

Back to top

バケツ関連の操作を提供する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}`

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

### 注記 ¶

#### Example URI

GET 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

以前に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}`

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

### 注記 ¶

#### Example URI

HEAD 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

    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`パラメータで指定された条件と、実際のオブジェクトのバージョンが異なる。

応答ヘッダの`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}/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"
      ]
    }

Generated by aglio on 25 Oct 2018