From 08ab982b67f0d89028b791a2019d288541496d0c Mon Sep 17 00:00:00 2001 From: Olha Livitchuk Date: Thu, 25 Jan 2024 16:33:31 +0100 Subject: [PATCH 1/4] FRW-6430 Data Exchange API Complex Endpoints for POST,PUT,PATCH --- .../202311.0/install-the-data-exchange-api.md | 12 +-- ...ow-to-send-request-in-data-exchange-api.md | 83 ++++++++++++++++++- 2 files changed, 89 insertions(+), 6 deletions(-) diff --git a/_includes/pbc/all/install-features/202311.0/install-the-data-exchange-api.md b/_includes/pbc/all/install-features/202311.0/install-the-data-exchange-api.md index 2ca47f47210..f4dad01cde1 100644 --- a/_includes/pbc/all/install-features/202311.0/install-the-data-exchange-api.md +++ b/_includes/pbc/all/install-features/202311.0/install-the-data-exchange-api.md @@ -20,7 +20,7 @@ Install the required features: Install the required modules using Composer: ```bash -composer require spryker/dynamic-entity-backend-api:"^1.0.0" spryker/dynamic-entity-gui:"^1.0.0" --update-with-dependencies +composer require spryker/dynamic-entity-backend-api:"^1.5.0" spryker/dynamic-entity-gui:"^1.0.0" --update-with-dependencies ``` {% info_block warningBox "Verification" %} @@ -377,12 +377,12 @@ dynamic_entity.validation.persistence_failed_duplicate_entry,"Failed to persist dynamic_entity.validation.persistence_failed_duplicate_entry,"Das Speichern der Daten ist fehlgeschlagen. Bitte überprüfen Sie die bereitgestellten Daten und versuchen Sie es erneut. Eintrag is doppelt vorhanden.",de_DE dynamic_entity.validation.entity_does_not_exist,"The entity could not be found in the database.",en_US dynamic_entity.validation.entity_does_not_exist,"Die Entität konnte in der Datenbank nicht gefunden werden.",de_DE -dynamic_entity.validation.invalid_field_type,"Invalid data type for field: %fieldName%",en_US -dynamic_entity.validation.invalid_field_type,"Ungültiger Datentyp: %fieldName%",de_DE +dynamic_entity.validation.invalid_field_type,"Invalid data type for field: %tableAlias%.%fieldName%",en_US +dynamic_entity.validation.invalid_field_type,"Ungültiger Datentyp: %tableAlias%.%fieldName%",de_DE dynamic_entity.validation.invalid_field_value,"Invalid data value for field: %fieldName%, row number: %rowNumber%. Field rules: %validationRules%",en_US dynamic_entity.validation.invalid_field_value,"Ungültiger Datenwert für das Feld: %fieldName%, Zeilennummer: %rowNumber%. Feldregeln: %validationRules%",de_DE -dynamic_entity.validation.required_field_is_missing,"The required field must not be empty. Field: '%fieldName%'",en_US -dynamic_entity.validation.required_field_is_missing,"Das erforderlich Feld darf nicht leer sein. Feld: '%fieldName%'",de_DE +dynamic_entity.validation.required_field_is_missing,"The required field must not be empty. Field: '%tableAlias%.%fieldName%'",en_US +dynamic_entity.validation.required_field_is_missing,"Das erforderlich Feld darf nicht leer sein. Feld: '%tableAlias%.%fieldName%'",de_DE dynamic_entity.validation.entity_not_found_or_identifier_is_not_creatable,"Entity `%identifier%` not found by identifier, and new identifier can not be persisted. Please update the request.",en_US dynamic_entity.validation.entity_not_found_or_identifier_is_not_creatable,"Entität `%identifier%` konnte anhand der ID nicht gefunden werden, und die neue ID kann nicht dauerhaft gespeichert werden. Bitte aktualisieren Sie die Anfrage.",de_DE dynamic_entity.validation.modification_of_immutable_field_prohibited,"Modification of immutable field `%fieldName%` is prohibited",en_US @@ -393,6 +393,8 @@ dynamic_entity.validation.provided_field_is_invalid,"The provided `%fieldName%` dynamic_entity.validation.provided_field_is_invalid,"Der angegebene `%fieldName%` ist falsch oder ungültig.",de_DE dynamic_entity.validation.relation_not_found,"Relation %relationName% not found. Please check the requested relation name and try again.",en_US dynamic_entity.validation.relation_not_found,"Beziehung %relationName% nicht gefunden. Bitte überprüfen Sie den angeforderten Beziehungsnamen und versuchen Sie es erneut.",de_DE +dynamic_entity.validation.relation_is_not_editable,"The relationship `%relationName%` is not editable by configuration.",en_US +dynamic_entity.validation.relation_is_not_editable,"Die Beziehung `%relationName%` kann nicht per Konfiguration bearbeitet werden.",de_DE dynamic_entity.validation.configuration_not_found,"Dynamic entity configuration for table alias `%aliasName%` not found.",en_US dynamic_entity.validation.configuration_not_found,"Dynamische Entitätskonfiguration für Tabellenalias `%aliasName%` nicht gefunden.",de_DE ``` diff --git a/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md b/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md index 81c7bef0c95..205119946f2 100644 --- a/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md +++ b/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md @@ -465,6 +465,86 @@ to ensure accurate and consistent data manipulation during `PUT` operations. {% endinfo_block %} +### Sending `POST`, `PATCH` and `PUT` requests with relationships + +To create or update an entity along with its related entities, you need to include the relationships directly in +the request payload. The payload should be structured to reflect the hierarchy and connections between the main entity +and its child entities. + +{% info_block infoBox %} + +Currently, our system does not support many-to-many relationships. Only one-to-one and one-to-many relationships are allowed. +This means each child entity can be associated with only one parent entity. + +{% endinfo_block %} + +The payload for these requests follows a nested structure where the main entity and its related entities are included within a data array. +Each object in the data array represents an instance of the main entity, and each related entity is nested within it. + +To be processed correctly, a relation chain must contain only existing relation names arranged in the correct sequence that aligns with the relation hierarchy. Otherwise, an error will be returned. See [error codes](#error-codes). + +```bash +POST /dynamic-entity/countries HTTP/1.1 +Host: glue-backend.mysprykershop.com +Content-Type: application/json +Accept: application/json +Authorization: Bearer {your_token} +Content-Length: 245 + +{ + "data": [ + { + "iso2_code": "DE", + "iso3_code": "DEU", + "name": "Germany", + "countryTaxRates": [ + { + "name": "Germany Standard", + "rate": "1.00" + } + ] + } + ] +} +``` + +Response sample: + +```json +{ + "data": [ + { + "iso2_code": "DE", + "iso3_code": "DEU", + "name": "Germany", + "postal_code_mandatory": null, + "postal_code_regex": null, + "id_country": 1, + "countryTaxRates": [ + { + "name": "Germany Standard", + "rate": "1.00", + "id_country_tax_rate": 1, + "fk_country": 1 + } + ] + } + ] +} +``` + +The response contains all columns from the `spy_country` table and the included `spy_tax_rate` table, +as configured in `spy_dynamic_entity_definition.definition`. Each column is identified using the `fieldVisibleName` +as the key, providing a comprehensive view of the table’s data in the API response. + +{% info_block infoBox %} + +For POST and PUT requests, which are used to create new entities, child entities receive their foreign key reference +to the parent entity only after the parent entity is created. The system automatically assigns the foreign key +to the child entities based on the newly created parent entity's ID. + +{% endinfo_block %} + #### Error codes Bellow, you can find a list of error codes that you can receive when sending `GET`, `POST`, `PATCH` or `PUT` requests. @@ -483,4 +563,5 @@ Bellow, you can find a list of error codes that you can receive when sending `GE | 1310 | Incomplete Request - missing identifier. | The request is incomplete. The identifier is missing. Check the request and try again. | | 1311 | The provided `field` is incorrect or invalid. | The request contains a field that isn't present in the configuration. Check the field names. | | 1312 | Dynamic entity configuration for table alias `alias` not found. | Make sure that you send the valid alias of the entity in the request. | -| 1313 | Relation `relation` not found. Please check the requested relation name and try again. | Make sure that the relation that you send in the relation chain is valid and present in the `spy_dynamic_entity_configuration_relation` table. | \ No newline at end of file +| 1313 | Relation `relation` not found. Please check the requested relation name and try again. | Make sure that the relation that you send in the relation chain is valid and present in the `spy_dynamic_entity_configuration_relation` table. | +| 1314 | The relationship `relation` is not editable by configuration. | Make sure that the relation that you send in the relation chain is configurable. | From 385ad4f6e614ae5131afbf92d9927a1d2576a921 Mon Sep 17 00:00:00 2001 From: Olha Livitchuk Date: Thu, 25 Jan 2024 17:12:14 +0100 Subject: [PATCH 2/4] FRW-6430 adjustments after tech review --- .../how-to-send-request-in-data-exchange-api.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md b/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md index 205119946f2..a997930256f 100644 --- a/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md +++ b/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md @@ -473,15 +473,22 @@ and its child entities. {% info_block infoBox %} -Currently, our system does not support many-to-many relationships. Only one-to-one and one-to-many relationships are allowed. -This means each child entity can be associated with only one parent entity. +Currently, our system does not support `many-to-many` relationships for POST, PATCH and PUT requests. +Only `one-to-one` and `one-to-many` relationships are allowed. This means each child entity can be associated +with only one parent entity. {% endinfo_block %} The payload for these requests follows a nested structure where the main entity and its related entities are included within a data array. Each object in the data array represents an instance of the main entity, and each related entity is nested within it. -To be processed correctly, a relation chain must contain only existing relation names arranged in the correct sequence that aligns with the relation hierarchy. Otherwise, an error will be returned. See [error codes](#error-codes). +To be processed correctly related entities must be defined with existing relation names, and they should be +organized to align with their hierarchical relationships in the database. +Incorrect or non-existent relation names or a misalignment in the hierarchy will lead to processing errors. +For a detailed list of potential errors, see [error codes](#error-codes). + +For POST, PATCH, and PUT requests the payload must accurately reflect the entity relationships. +Each entity in the request should include its corresponding related entities, structured as nested objects within the payload. ```bash POST /dynamic-entity/countries HTTP/1.1 From 3e4c124cdc023182b33c54378ed832df1198d106 Mon Sep 17 00:00:00 2001 From: Olha Livitchuk Date: Thu, 25 Jan 2024 17:33:03 +0100 Subject: [PATCH 3/4] FRW-6430 adjustments after tech review --- .../how-to-send-request-in-data-exchange-api.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md b/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md index a997930256f..b0c86a5709b 100644 --- a/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md +++ b/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md @@ -483,7 +483,16 @@ The payload for these requests follows a nested structure where the main entity Each object in the data array represents an instance of the main entity, and each related entity is nested within it. To be processed correctly related entities must be defined with existing relation names, and they should be -organized to align with their hierarchical relationships in the database. +organized to align with their hierarchical relationships in the database, corresponding to the relationships +defined in tables like `spy_dynamic_entity_configuration_relation` and `spy_dynamic_entity_configuration_relation_field_mapping`: + +- `spy_dynamic_entity_configuration_relation` specifies the relationships between parent and child entities. Each record links a parent entity to a child entity. +- `spy_dynamic_entity_configuration_relation_field_mapping` contains the field mappings between related entities. + +The hierarchical relationships are primarily defined by the foreign key references in these tables. +For example, `spy_dynamic_entity_configuration_relation` uses foreign keys to establish connections between +parent and child configurations in `spy_dynamic_entity_configuration`. + Incorrect or non-existent relation names or a misalignment in the hierarchy will lead to processing errors. For a detailed list of potential errors, see [error codes](#error-codes). From 2b7838904edcaa4f65f2dd1980852235595af1a1 Mon Sep 17 00:00:00 2001 From: Helen Kravchenko Date: Thu, 1 Feb 2024 11:54:12 +0100 Subject: [PATCH 4/4] Update how-to-send-request-in-data-exchange-api.md --- .../how-to-send-request-in-data-exchange-api.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md b/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md index b0c86a5709b..f7943e14c51 100644 --- a/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md +++ b/docs/pbc/all/data-exchange/202311.0/tutorials-and-howtos/how-to-send-request-in-data-exchange-api.md @@ -465,7 +465,7 @@ to ensure accurate and consistent data manipulation during `PUT` operations. {% endinfo_block %} -### Sending `POST`, `PATCH` and `PUT` requests with relationships +### Sending `POST`, `PATCH`б and `PUT` requests with relationships To create or update an entity along with its related entities, you need to include the relationships directly in the request payload. The payload should be structured to reflect the hierarchy and connections between the main entity @@ -473,8 +473,8 @@ and its child entities. {% info_block infoBox %} -Currently, our system does not support `many-to-many` relationships for POST, PATCH and PUT requests. -Only `one-to-one` and `one-to-many` relationships are allowed. This means each child entity can be associated +Currently, our system doesn't support `many-to-many` relationships for POST, PATCH, and PUT requests. +Only `one-to-one` and `one-to-many` relationships are allowed. This means that each child entity can be associated with only one parent entity. {% endinfo_block %} @@ -482,9 +482,7 @@ with only one parent entity. The payload for these requests follows a nested structure where the main entity and its related entities are included within a data array. Each object in the data array represents an instance of the main entity, and each related entity is nested within it. -To be processed correctly related entities must be defined with existing relation names, and they should be -organized to align with their hierarchical relationships in the database, corresponding to the relationships -defined in tables like `spy_dynamic_entity_configuration_relation` and `spy_dynamic_entity_configuration_relation_field_mapping`: +For correct processing, make sure that related entities are defined with existing relation names. Also, organize them in alignment with their hierarchical relationships in the database, corresponding to the relationships defined in tables like `spy_dynamic_entity_configuration_relation` and `spy_dynamic_entity_configuration_relation_field_mapping`: - `spy_dynamic_entity_configuration_relation` specifies the relationships between parent and child entities. Each record links a parent entity to a child entity. - `spy_dynamic_entity_configuration_relation_field_mapping` contains the field mappings between related entities. @@ -493,11 +491,11 @@ The hierarchical relationships are primarily defined by the foreign key referenc For example, `spy_dynamic_entity_configuration_relation` uses foreign keys to establish connections between parent and child configurations in `spy_dynamic_entity_configuration`. -Incorrect or non-existent relation names or a misalignment in the hierarchy will lead to processing errors. -For a detailed list of potential errors, see [error codes](#error-codes). +Incorrect or non-existent relation names or a misalignment in the hierarchy leads to processing errors. +For a detailed list of potential errors, see [Error codes](#error-codes). For POST, PATCH, and PUT requests the payload must accurately reflect the entity relationships. -Each entity in the request should include its corresponding related entities, structured as nested objects within the payload. +Make sure that each entity in the request includes its corresponding related entities, structured as nested objects within the payload. ```bash POST /dynamic-entity/countries HTTP/1.1