From 4cb6515b7e243a8bbdc0f96e5e0c0c9a13e18c34 Mon Sep 17 00:00:00 2001 From: Kazuhito Suda Date: Thu, 11 Jan 2024 03:10:21 +0900 Subject: [PATCH 1/2] Fix typo --- doc/manuals/orion-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/manuals/orion-api.md b/doc/manuals/orion-api.md index 671606686b..a3aaaf557c 100644 --- a/doc/manuals/orion-api.md +++ b/doc/manuals/orion-api.md @@ -4703,7 +4703,7 @@ For action type `update` or `delete`: } ``` -For action type `appendStrict`:` +For action type `appendStrict`: * If in *all* entities in `entities` there was a *full fail* due to existing attributes: From a2e280d6efc181e8ef57a90fa8b63ee075fa0375 Mon Sep 17 00:00:00 2001 From: Kazuhito Suda Date: Thu, 11 Jan 2024 03:12:14 +0900 Subject: [PATCH 2/2] (JP) ADD doc about PartialUpdates reporting in error responses (#4447) --- doc/manuals.jp/orion-api.md | 328 +++++++++++++++++++++++++++++++++--- 1 file changed, 305 insertions(+), 23 deletions(-) diff --git a/doc/manuals.jp/orion-api.md b/doc/manuals.jp/orion-api.md index bc4a4f0c7d..07055c136a 100644 --- a/doc/manuals.jp/orion-api.md +++ b/doc/manuals.jp/orion-api.md @@ -2822,6 +2822,9 @@ _**レスポンス・コード**_ - 成功したオペレーションでは、200 OK を使用します - エラーは、2xx 以外のものと、(オプションで) エラー・ペイロードを使用します。詳細については、 [エラー・レスポンス](#error-responses)のサブセクションを参照してください +- エラーでは、2xx 以外のコードとエラー・ペイロードが使用されます: + - エンティティが見つからず、404 Not Found になる場合 (次のサブセクションを参照) + - [エラー・レスポンス](#error-responses) の一般ドキュメントで追加のケースを確認してください _**レスポンス・ヘッダ**_ @@ -2829,8 +2832,17 @@ _**レスポンス・ヘッダ**_ _**レスポンス・ペイロード**_ -レスポンスは、id で識別されるエンティティを表すオブジェクトです。オブジェクトは、JSON エンティティ表現形式 -([JSON エンティティ表現](#json-entity-representation)のセクションと、 +エンティティが見つからない場合: + +``` +{ + "description": "The requested entity has not been found. Check type and id", + "error": "NotFound" +} +``` + +エンティティが見つかった場合、レスポンスは ID で識別されるエンティティを表すオブジェクトになります。 +オブジェクトは、JSON エンティティ表現形式 ([JSON エンティティ表現](#json-entity-representation)のセクションと、 [簡略化されたエンティティ表現](#simplified-entity-representation)および、[部分的表現](#partial-representations) のセクションで説明されています) に従います。 @@ -2906,8 +2918,9 @@ _**リクエスト・ヘッダ**_ _**レスポンス・コード**_ - 成功したオペレーションでは、200 OK を使用します -- エラーは、2xx 以外のものと、(オプションで) エラー・ペイロードを使用します。詳細については、 - [エラー・レスポンス](#error-responses)のサブセクションを参照してください +- エラーでは、2xx 以外のコードとエラー・ペイロードが使用されます: + - エンティティが見つからず、404 Not Found になる場合 (次のサブセクションを参照) + - [エラー・レスポンス](#error-responses) の一般ドキュメントで追加のケースを確認してください _**レスポンス・ヘッダ**_ @@ -2915,8 +2928,17 @@ _**レスポンス・ヘッダ**_ _**レスポンス・ペイロード**_ -ペイロードは、URL パラメータの id で識別されるエンティティを表すオブジェクトです。オブジェクトは JSON -エンティティ表現形式 ([JSON エンティティ表現](#json-entity-representation)のセクションと、 +エンティティが見つからない場合: + +``` +{ + "description": "The requested entity has not been found. Check type and id", + "error": "NotFound" +} +``` + +エンティティが見つかった場合、ペイロードは、URL パラメータの ID によって識別されるエンティティを表すオブジェクトです。 +オブジェクトは JSON エンティティ表現形式 ([JSON エンティティ表現](#json-entity-representation)のセクションと、 [簡略化されたエンティティ表現](#simplified-entity-representation)および、[部分表現](#partial-representations) のセクションで説明されています) に従いますが、`id` フィールドと `type` フィールドは省略されます。 @@ -3014,8 +3036,45 @@ JSON エンティティ表現形式 ([JSON エンティティ表現](#json-entit _**レスポンス・コード**_ - 成功したオペレーションでは、204 No Content を使用します -- エラーは、2xx 以外のものと、(オプションで) エラー・ペイロードを使用します。詳細については、 - [エラー・レスポンス](#error-responses)のサブセクションを参照してください +- エラーでは、2xx 以外のコードとエラー・ペイロードが使用されます: + - エンティティが見つからず、404 Not Found になる場合 (次のサブセクションを参照) + - `append` オプションが使用されたときに、属性が存在していて、422 Unprocessable Content になる場合 (次のサブセクションを参照) + - [エラー・レスポンス](#error-responses) の一般ドキュメントで追加のケースを確認してください + +_**レスポンス・ペイロード**_ + +エンティティが見つからない場合: + +``` +{ + "description": "The requested entity has not been found. Check type and id", + "error": "NotFound" +} +``` + +`append` オプションが使用されたときに、*すべて* の属性が存在する場合: + +``` +{ + "description": "one or more of the attributes in the request already exist: E/T - [ A, B ]", + "error": "Unprocessable" +} +``` + +`append` オプションが使用されたときに、*一部* (すべてではない) 属性が存在する場合 (部分更新): + +``` +{ + "description": "one or more of the attributes in the request already exist: E/T - [ B ]", + "error": "PartialUpdate" +} +``` + +`description` 内のエンティティ型は、リクエストにエンティティ型が含まれている場合にのみ表示されます。それ以外の場合は省略されます: + +``` +"description": "one or more of the attributes in the request already exist: E - [ B ]", +``` @@ -3081,6 +3140,46 @@ _**レスポンス**_ - 成功したオペレーションでは、204 No Content を使用します - エラーは、2xx 以外のものと、(オプションで) エラー・ペイロードを使用します。詳細については、 [エラー・レスポンス](#error-responses)のサブセクションを参照してください +- エラーでは、2xx 以外のコードとエラー・ペイロードが使用されます: + - エンティティが見つからず、404 Not Found になる場合 (次のサブセクションを参照) + - 属性が存在しないで、422 Unprocessable Content になる場合 (次のサブセクションを参照) + - [エラー・レスポンス](#error-responses) の一般ドキュメントで追加のケースを確認してください + +_**レスポンス・ペイロード**_ + +エンティティが見つからない場合: + +``` +{ + "description": "The requested entity has not been found. Check type and id", + "error": "NotFound" +} +``` + +リクエストに属性が *何も存在しない* 場合: + +``` +{ + "description": "do not exist: E/T - [ C, D ]", + "error": "Unprocessable" +} +``` + +*一部* (すべてではない) 属性が存在しない場合 (部分更新): + +``` +{ + "description": "do not exist: E/T - [ C ]", + "error": "PartialUpdate" +} +``` + + +`description` 内のエンティティ型は、リクエストにエンティティ型が含まれている場合にのみ表示されます。それ以外の場合は省略されます: + +``` +"description": "do not exist: E - [ C ]", +``` @@ -3143,8 +3242,20 @@ _**リクエスト・ペイロード**_ _**レスポンス・コード**_ - 成功したオペレーションでは、204 No Content を使用します -- エラーは、2xx 以外のものと、(オプションで) エラー・ペイロードを使用します。詳細については、 - [エラー・レスポンス](#error-responses)のサブセクションを参照してください +- エラーでは、2xx 以外のコードとエラー・ペイロードが使用されます: + - エンティティが見つからず、404 Not Found になる場合 (次のサブセクションを参照) + - [エラー・レスポンス](#error-responses) の一般ドキュメントで追加のケースを確認してください + +_**レスポンス・ペイロード**_ + +エンティティが見つからない場合: + +``` +{ + "description": "The requested entity has not been found. Check type and id", + "error": "NotFound" +} +``` @@ -3176,8 +3287,20 @@ _**リクエスト・ヘッダ**_ _**レスポンス・コード**_ - 成功したオペレーションでは、204 No Content を使用します -- エラーは、2xx 以外のものと、(オプションで) エラー・ペイロードを使用します。詳細については、 - [エラー・レスポンス](#error-responses)のサブセクションを参照してください +- エラーでは、2xx 以外のコードとエラー・ペイロードが使用されます: + - エンティティが見つからず、404 Not Found になる場合 (次のサブセクションを参照) + - [エラー・レスポンス](#error-responses) の一般ドキュメントで追加のケースを確認してください + +_**レスポンス・ペイロード**_ + +エンティティが見つからない場合: + +``` +{ + "description": "The requested entity has not been found. Check type and id", + "error": "NotFound" +} +``` @@ -3308,8 +3431,29 @@ _**リクエスト・ペイロード**_ _**レスポンス・コード**_ - 成功したオペレーションでは、204 No Content を使用します -- エラーは、2xx 以外のものと、(オプションで) エラー・ペイロードを使用します。詳細については、 - [エラー・レスポンス](#error-responses)のサブセクションを参照してください +- エラーでは、2xx 以外のコードとエラー・ペイロードが使用されます: + - エンティティまたは属性が見つからず、404 Not Found になる場合 (次のサブセクションを参照) + - [エラー・レスポンス](#error-responses) の一般ドキュメントで追加のケースを確認してください + +_**レスポンス・ペイロード**_ + +エンティティが見つからない場合: + +``` +{ + "description": "The requested entity has not been found. Check type and id", + "error": "NotFound" +} +``` + +属性が見つからない場合: + +``` +{ + "description": "The entity does not have such an attribute", + "error": "NotFound" +} +``` @@ -3342,8 +3486,29 @@ _**リクエスト・ヘッダ**_ _**レスポンス・コード**_ - 正常なオペレーションには、204 No Content を使用します -- エラーは、2xx 以外のものと、(オプションで) エラー・ペイロードを使用します。詳細については、 - [エラー・レスポンス](#error-responses)のサブセクションを参照してください +- エラーでは、2xx 以外のコードとエラー・ペイロードが使用されます: + - エンティティまたは属性が見つからず、404 Not Found になる場合 (次のサブセクションを参照) + - [エラー・レスポンス](#error-responses) の一般ドキュメントで追加のケースを確認してください + +_**レスポンス・ペイロード**_ + +エンティティが見つからない場合: + +``` +{ + "description": "The requested entity has not been found. Check type and id", + "error": "NotFound" +} +``` + +属性が見つからない場合: + +``` +{ + "description": "The entity does not have such an attribute", + "error": "NotFound" +} +``` @@ -3387,8 +3552,10 @@ _**リクエスト・ヘッダ**_ _**レスポンス・コード**_ - 成功したオペレーションでは、200 OK を使用します -- エラーは、2xx 以外のものと、(オプションで) エラー・ペイロードを使用します。詳細については、 - [エラー・レスポンス](#error-responses)のサブセクションを参照してください +- エラーでは、2xx 以外のコードとエラー・ペイロードが使用されます: + - エンティティまたは属性が見つからず、404 Not Found になる場合 (次のサブセクションを参照) + - コンテンツが受け入れられないときに、406 Not Acceptable になる場合 (次のサブセクションを参照) + - [エラー・レスポンス](#error-responses) の一般ドキュメントで追加のケースを確認してください _**レスポンス・ヘッダ**_ @@ -3396,7 +3563,25 @@ _**レスポンス・ヘッダ**_ _**レスポンス・ペイロード**_ -レスポンス・ペイロードは、オブジェクト、配列、文字列、数値、ブール値、または属性の値を持つ null にすることができます。 +エンティティが見つからない場合: + +``` +{ + "description": "The requested entity has not been found. Check type and id", + "error": "NotFound" +} +``` + +属性が見つからない場合: + +``` +{ + "description": "The entity does not have such an attribute", + "error": "NotFound" +} +``` + +エンティティと属性の両方が見つかった場合、レスポンス・ペイロードはオブジェクト、配列、文字列、数値、ブール値、または属性の値を持つ null になります。 - 属性値が JSON 配列またはオブジェクトの場合: - `Accept` ヘッダを `application/json` または `text/plain` に展開できる場合、レスポンス・タイプが @@ -3486,8 +3671,29 @@ _**リクエスト・ペイロード**_ _**レスポンス・コード**_ - 成功したオペレーションでは、200 OK を使用します -- エラーは、2xx 以外のものと、(オプションで) エラー・ペイロードを使用します。詳細については、 - [エラー・レスポンス](#error-responses)のサブセクションを参照してください +- エラーでは、2xx 以外のコードとエラー・ペイロードが使用されます: + - エンティティまたは属性が見つからず、404 Not Found になる場合 (次のサブセクションを参照) + - [エラー・レスポンス](#error-responses) の一般ドキュメントで追加のケースを確認してください + +_**レスポンス・ペイロード**_ + +エンティティが見つからない場合: + +``` +{ + "description": "The requested entity has not been found. Check type and id", + "error": "NotFound" +} +``` + +属性が見つからない場合: + +``` +{ + "description": "The entity does not have such an attribute", + "error": "NotFound" +} +``` @@ -4548,8 +4754,84 @@ _**リクエスト・ペイロード**_ _**レスポンス・コード**_ - 成功したオペレーションでは、204 No Content を使用します -- エラーは、2xx 以外のものと、(オプションで) エラー・ペイロードを使用します。詳細については、 - [エラー・レスポンス](#error-responses)のサブセクションを参照してください +- エラーでは、2xx 以外のコードとエラー・ペイロードが使用されます: + - `update`, `delete` または `replace` 時に `entities` フィールドにエンティティが存在しなければ、404 Not Found になります (次のサブセクションを参照) + - そのほかの場合は、422 Unprocessable Content になります (次のサブセクションを参照) + - [エラー・レスポンス](#error-responses) の一般ドキュメントで追加のケースを確認してください + +_**レスポンス・ペイロード**_ + +アクション・タイプが `replace` の場合: + +- `entities` 内にエンティティが *何も*存在しない場合: + +``` +{ + "description": "do not exist: F/T - [entity itself], G/T [entity itself]", + "error": "NotFound" +} +``` + +- `entities` 内にエンティティの *いずれか (すべてではない)* が存在しない場合 (部分更新): + +``` +{ + "description": "do not exist: G/T - [entity itself]", + "error": "PartialUpdate" +} +``` + +アクション・タイプが `update` または `delete` の場合: + +- `entities` 内にエンティティが *何も*存在しない場合: + +``` +{ + "description": "do not exist: F/T - [entity itself], G/T [entity itself]", + "error": "NotFound" +} +``` + +- `entities` に少なくとも1つのエンティティが存在し、既存のエンティティの *すべて* で属性の欠落により *完全な失敗* が発生した場合: + +``` +{ + "description": "do not exist: E/T - [ C, D ], G/T [entity itself]", + "error": "Unprocessable" +} +``` + +- `entities` 内に少なくとも1つのエンティティが存在し、既存のエンティティの *少なくとも1つ*に、*少なくとも*1つの属性が存在するが、すべてのエンティティが存在するわけではない、 + またはすべてのエンティティが存在するが、少なくとも1つのエンティティに少なくとも1つの属性が欠落している場合 (部分更新): + +``` +{ + "description": "do not exist: E/T - [ D ], G/T [entity itself]", + "error": "PartialUpdate" +} +``` + +アクション・タイプが `appendStrict` の場合: + +- `entities` 内の *すべて* エンティティで、既存の属性が原因で*完全な失敗*があった場合: + +{ + "description": "one or more of the attributes in the request already exist: E1/T - [ A, B ], E2/T - [ A, B ]", + "error": "Unprocessable" +} + +- *少なくとも*1つの属性の `entities` 内の *少なくとも 1 つのエンティティ* で成功したが、 `entities` 内のすべてのエンティティが完全に成功したわけではない場合 (部分更新): + +{ + "description": "one or more of the attributes in the request already exist: E2/T - [ A, B ]", + "error": "PartialUpdate" +} + +`description` 内のエンティティ型は、リクエストにエンティティ型が含まれている場合にのみ表示されます。それ以外の場合は省略されます: + +``` +"description": "one or more of the attributes in the request already exist: E2 - [ A, B ]" +```