Google AIPs 02 - kntmr-blog

前回の続き。

気になるところを読んでみる。メモ。

URI にはリソース名を含む (name)
- (google.api.field_behavior) = REQUIRED
- それ以外のパラメータはクエリパラメータとする
google.api.method_signature
name 以外のフィールドは含めない
リソースや親リソースへのアクセス権限がない場合は PERMISSION_DENIED を返す
リクエストしたリソースや親リソースが存在しない場合は NOT_FOUND を返す

親リソースを指定する (parent)
- (google.api.field_behavior) = REQUIRED
- それ以外のパラメータはクエリパラメータとする
page_size, page_token はすべてのリクエストで指定する
- ただ、省略した場合のデフォルトを文書化せよって書いてある
- 最大値を文書化する (最大値を超える場合は最大値に丸める)
- 無効なリクエストは INVALID_ARGUMENT を返す
next_page_token
- すべてのレスポンスメッセージに含める
- 最終ページの場合は設定しない (AIP-158 では must be empty って書いてる)
total_size
- フィルタリングしている場合はフィルタされた結果を返す
order_by
- カンマ区切り可
- サブフィールド (foo.x, bar.y)
filter
- AIP-160
- たぶん filter='status=XXX OR status=YYY' のような使い方っぽい
show_deleted
- 論理削除or削除待ちのリソースを返却するかどうか
- モノによっては削除取り消しができるようにするため

google.longrunning.Operation
リソースを追加するコレクションの親リソースを指定する (parent)
- (google.api.field_behavior) = REQUIRED
リクエストにリソース ID を含める
- リソース名 (name) の最終セグメント
- ユーザーが ID を指定できるようにする
  - 自動採番のときは OPTIONAL にする
- リソースそのものではなくリクエストメッセージに含める
- ID が指定された場合はリソースの name は無視する (というか Create のときは空のはず)
リソース名が重複する場合は ALREADY_EXISTS を返す
- 重複リソースの参照権限がない場合は PERMISSION_DENIED を返す
Long-running create
- AIP-151
- リソースが使用不可であることを List, Get のレスポンスとして enum で返すイメージ

更新したフィールドすべてをレスポンスで返す
- update_mask で指定したフィールドを含む
- INPUT_ONLY のフィールドは返さない
PATCH メソッドで部分的な更新をサポートする
- リソースの全置換のみサポートする場合は PUT でもいい
- 部分更新をサポートする場合はリクエストに update_mask を含める
  - google.protobuf.FieldMask
allow_missing=true
- リソースが存在しない場合は新しく作成する
- この場合は update_mask は無視される (すべてのフィールドが保存される)
- allow_missing=true 以外でリソースが存在しない場合は NOT_FOUND を返す
etag
- リソースに含める
- サーバーで計算した値と一致する場合のみリクエストを処理する
- 一致しない場合は ABORTED エラーを返す

空のレスポンスを返す
Soft delete ではリソースを返す
Long-running delete
- google.longrunning.Operation
force=true
- 該当する子リソースを削除する
- force=true 以外で子リソースが存在する場合は FAILED_PRECONDITION を返す
etag
- Update と同様
allow_missing=true
- リソースが存在しない場合は何もせず成功を返す
- allow_missing=true 以外でリソースが存在しない場合は NOT_FOUND を返す