Uploaded image for project: 'OASIS Open Data Protocol (OData) TC'
  1. OASIS Open Data Protocol (OData) TC
  2. ODATA-37

UPSERT: allow PUT and PATCH to the URL of a not yet existing entity to create this entity

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: V4.0_WD01
    • Fix Version/s: V4.0_WD01
    • Component/s: Protocol
    • Labels:
      None
    • Environment:

      [Proposed]

    • Proposal:
      Hide

      Allow PUT or PATCH to a URL that identifies a single, not yet existing entity to insert this entity.

      Adapt the last paragraph of section 8.2.4:

      If specified, the request MUST only be invoked if the specified value matches the current ETag value of the entity. If the value does not match the current ETag value of the entity for a Data Modification Request or Action Request, the service MUST respond with 412 Precondition Failed and MUST ensure that no data is modified as a result of the request. NEW: If the addressed entity does not exist, the provided ETag value is considered not to match.

      Adapt first paragraph of section 10.3.2:

      To create an entity in a collection, send a POST request to that collection's URL. or a PUT or PATCH request to the entity's URL (collection's URL followed by entity key specification for the single entity). For a PUT request the request body MUST contain a single valid entity representation. For a PATCH request the request body MUST contain a partial representation of a single valid entity.

      Note: a PUT or PATCH request targets the entity URL, not the entity set URL, so the client chooses the values of the key properties, not the server. If this is not permissible (e.g. if the key values come from a server-managed number range), the request MUST be rejected.

      UPSERT is shallow, i.e. no inlined related entities allowed. Same behavior as for PATCH/PUT

      Use 201 with content for insert plus other insert behavior (location header, ...), 204/200 for update (depending on preferences)

      UPSERT for media entities not possible because INSERT requires media resource, UPDATE requires media entity in body

      POST and UPSERT only possible to navigation properties that have a binding because otherwise the server may not know where to store the entity

      Accepted: https://www.oasis-open.org/committees/download.php/48549/odata-meeting-29_on-20130314-minutes.html#odata-37

      Show
      Allow PUT or PATCH to a URL that identifies a single, not yet existing entity to insert this entity. Adapt the last paragraph of section 8.2.4: If specified, the request MUST only be invoked if the specified value matches the current ETag value of the entity. If the value does not match the current ETag value of the entity for a Data Modification Request or Action Request, the service MUST respond with 412 Precondition Failed and MUST ensure that no data is modified as a result of the request. NEW: If the addressed entity does not exist, the provided ETag value is considered not to match. Adapt first paragraph of section 10.3.2: To create an entity in a collection, send a POST request to that collection's URL. or a PUT or PATCH request to the entity's URL (collection's URL followed by entity key specification for the single entity). For a PUT request the request body MUST contain a single valid entity representation. For a PATCH request the request body MUST contain a partial representation of a single valid entity. Note: a PUT or PATCH request targets the entity URL, not the entity set URL, so the client chooses the values of the key properties, not the server. If this is not permissible (e.g. if the key values come from a server-managed number range), the request MUST be rejected. UPSERT is shallow, i.e. no inlined related entities allowed. Same behavior as for PATCH/PUT Use 201 with content for insert plus other insert behavior (location header, ...), 204/200 for update (depending on preferences) UPSERT for media entities not possible because INSERT requires media resource, UPDATE requires media entity in body POST and UPSERT only possible to navigation properties that have a binding because otherwise the server may not know where to store the entity Accepted: https://www.oasis-open.org/committees/download.php/48549/odata-meeting-29_on-20130314-minutes.html#odata-37
    • Resolution:
      Show
      Accepted: https://www.oasis-open.org/committees/download.php/49026/odata-meeting-34_on-20130425_26-F2F-minutes.html#odata-37

      Description

      HTTP semantics of PUT and PATCH allow inserting new entities; PUT specifies the desired after-image.

      Example:

      PUT ~/Employees(12345)

      <full entity body>

      would update employee 12345 if it exists, and create it if it doesn't exist yet.

      Note: the PUT request targets the entity URL, not the entity set URL, so the client chooses the values of the key properties, not the server. Where this is not permissible (e.g. if the key comes from a server-managed number range), the request MUST be rejected.

      This is desirable in some cases and saves GET requests to check for existence.

      If the client only wants to update existing resources, it MAY include an If-Match header, either with a specific ETag value, or with "*".

      RFC2616, section 14.24 explicitly describes If-Match:* for "update only if existing".

      If ODATA-39 is applied as proposed, the new paragraph in section 8.2.4 must be relaxed to allow inserting new entities without specifying an If-Match request header.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              handl Ralf Handl
            • Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: