[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [OASIS Issue Tracker] (ODATA-666) Define Deep Update and Deep Upsert operations
[ https://issues.oasis-open.org/browse/ODATA-666?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=62084#comment-62084 ]
Michael Pizzo commented on ODATA-666:
-------------------------------------
Need to consider semantics of a PUT against a single entity where the payload contains nested entities.
> Define Deep Update and Deep Upsert operations
> ---------------------------------------------
>
> Key: ODATA-666
> URL: https://issues.oasis-open.org/browse/ODATA-666
> Project: OASIS Open Data Protocol (OData) TC
> Issue Type: Improvement
> Components: Implementing OData, OData ATOM Format, OData JSON Format, OData Protocol
> Affects Versions: V4.0_OS
> Environment: Set Operations; [Proposed]
> Reporter: Ralf Handl
> Assignee: Ralf Handl
> Labels: AdoptionBlocker, Usability
> Fix For: V4.01_WD01
>
>
> Similar to Deep Insert allow including nested entities that may already exist, in which case they are updated.
> Also allow nested "tombstones" to remove entities.
> Allow entity references to just create relations as an alternative to odata.bind (in the long run: retire odata.bind and use references everywhere).
> Use odata.etag annotation for conditional update of nested entities.
> Original Proposal for sanity check:
> Document changes
> part1-protocol
>
> 11.4.3 Update an Entity
> Replace para #7 with:
> The entity MAY contain related entities or entity references as inline content. For single-valued navigation properties this replaces the relationship. For collection-valued navigation properties this replaces the contents of the collection for the specified entites.
> may either add to the relationship (link to 11.4.3.1-see below) or update related entities (link to 11.4.3.2-see below). Combining these two variants for updating a single collection-valued navigation property results in a 400 Bad Request error.
> (new section providing a guideline for updating links) 11.4.3.1 Add Links to Related Entities When Updating an Entity
> To update an entity by adding further links to existing entities, the request includes bind operations on the corresponding navigation property. However, using such bind operations is deprecated. The preferred method is to update the related entities (link to 11.4.3.2).
> (new section) 11.4.3.2 Update Related Entities When Updating an Entity
> The request to update an entity MAY contain collection-valued navigation properties with updated representations of the set of entities related according to the relationship represented by the navigation property. This set MAY be a combination of entities as inline content in the request body, which is referred to as "deep update", entity references, deleted links and deleted entities.
> If the update operation is triggered by a PUT request, the value of a navigation property represents the full set of related entities. Any entity in the relation that is not included in the request, either as an entity or entity reference, is removed from the relation. Any entity that is included as an entity reference is retained without changes if it was already related or added as a member if it wasn't. Any entity represented inline is updated (link to 11.4.3) if it is already related and upserted otherwise (link to 11.4.4). A PUT request MUST NOT include deleted links and deleted entities.
> If the update operation is triggered by a PATCH request with the "delta format" for that nested entity collection, the value of a navigation property represents changes to the set of related entities. Any entity in the relation that is not included in the request is retained without changes. Any entity that is included as an entity reference is retained without changes if it was already related or added as a member if it wasn't. Any entity represented inline is updated (link to 11.4.3) if it is already related and upserted otherwise (link to 11.4.4). A deleted link is processed as removed reference for that navigation property (link to 11.4.6.2). A deleted entity is processed as deleted link and then deleted (link to 11.4.5). Comment: The collection may contain added links.
> If the update operation is triggered by a PATCH request without the "delta format" for that nested entity collection, we apply PUT semantics for the collection membership, and PATCH semantics for the rest.
> An entity being part of the deep update MUST include its entity-id or its full set of key values for identification. It is an error to specify an entity reference that does not identify an existing entity.
> The service MUST NOT treat an update request for related entities with an odata.etag annotation as an insert and must use the etag for conditional updates of existing members. Conflicts will be signaled via status code 412 (precondition failed).
>
> Upon failure of the operation, the service MUST NOT modify any of the entities in the request in order to prevent a partial update.
> (Guideline for linking entities) 11.4.2.1 Link to Related Entities When Creating an Entity
> - Replace sentence #2 with "The preferred method of providing such entity-ids is through entity references; the use of bind operations is deprecated".
>
> json-format
> In section 4.5.7 Annotation odata.id
> Add after para #2:
> The odata.id annotation MAY appear in deep update requests to identify entities to be updated.
> In section 8.4 Deep Inserts
> Remove sentence #2. ("Deep inserts are not allowed in update operations using PUT or PATCH requests.")
> Add section 8.5 Deep Update (shift all subsequent sections)
> When updating an entity with a PUT request, the request body MAY contain related entities specified using the same representation as for an expanded navigation property.
> When updating an entity with a PATCH request, the request body MAY contain changes to related entities specified using the representation as for an expanded navigation property that MAY also comprise deleted links and deleted entities.
>
> atom-format
>
> In section 8.4 Deep Inserts
> Remove sentence #2. ("Deep inserts are not allowed in update operations using PUT or PATCH requests.")
> Add section 8.5 Deep Update (shift all subsequent sections)
> When updating an entity with a PUT request, the request body MAY contain related entities specified using the same representation as for an expanded navigation property.
> When updating an entity with a PATCH request, the request body MAY contain changes to related entities specified using the representation as for an expanded navigation property that MAY also comprise deleted links and deleted entities.
--
This message was sent by Atlassian JIRA
(v6.2.2#6258)
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]