From 3efefb2d5bb9e5c9eedb75f793d69e7e0e5b5bc0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= Date: Thu, 12 Sep 2024 12:16:04 +0200 Subject: [PATCH] Extend example --- docs/odata-protocol/odata-protocol.html | 207 ++++++++++++----------- docs/odata-protocol/odata-protocol.md | 18 +- odata-protocol/11.4 Data Modification.md | 18 +- 3 files changed, 132 insertions(+), 111 deletions(-) diff --git a/docs/odata-protocol/odata-protocol.html b/docs/odata-protocol/odata-protocol.html index aada541c..bedbb3a2 100644 --- a/docs/odata-protocol/odata-protocol.html +++ b/docs/odata-protocol/odata-protocol.html @@ -2485,18 +2485,23 @@

81: read an entity and select a stream property

GET http://host/service/Products(1)?$select=Thumbnail

would only include control information for the stream property, not the stream data itself

-
{
-  "@context": "http://host/service/$metadata#Products/$entity",
-  …
-  "Thumbnail@mediaReadLink": "http://server/Thumbnail546.jpg",
-  "Thumbnail@mediaEditLink": "http://server/uploads/Thumbnail546.jpg",
-  …
-}
+
{
+  "@context": "http://host/service/$metadata#Products/$entity",
+  …
+  "Thumbnail@mediaReadLink": "http://server/Thumbnail546.jpg",
+  "Thumbnail@mediaEditLink": "http://server/uploads/Thumbnail546.jpg",
+  …
+}

The stream data can then be requested using the media read link:

GET http://server/Thumbnail546.jpg
@@ -2698,12 +2703,12 @@

Core.PositionalInsert term (see OData-VocCore) support inserting items at a specific location via POST requests to the collection URL using the $index system query option. The value of the $index system query option is the zero-based ordinal position where the item is to be inserted. The ordinal positions of items within the collection greater than or equal to the inserted position are increased by one. A negative ordinal number indexes from the end of the collection, with -1 representing an insert as the last item in the collection.

Example 84: Insert a new email address at the second position

-
POST /service/Customers('ALFKI')/EmailAddresses?$index=1
-Content-Type: application/json
-
-{
-  "value": "alfred@futterkiste.de"
-}
+
POST /service/Customers('ALFKI')/EmailAddresses?$index=1
+Content-Type: application/json
+
+{
+  "value": "alfred@futterkiste.de"
+}
@@ -2759,12 +2764,12 @@

For collections of structured type, the body of the request MUST be a full or partial representation of an instance of the collection’s structured type. Each member of the potentially filtered collection is updated using PATCH semantics. Structured types MAY include nested collections or delta collections, in which case the semantics described in Update a Collection of Entities applies.

Example 85: change the color of all beige-brown products

-
PATCH /service/Products/$filter(@bar)/$each?@bar=Color eq 'beige-brown'
-Content-Type: application/json
-
-{
-  "Color": "taupe"
-}
+
PATCH /service/Products/$filter(@bar)/$each?@bar=Color eq 'beige-brown'
+Content-Type: application/json
+
+{
+  "Color": "taupe"
+}

The response, if requested, is a collection payload containing the updated representation of each member identified by the request. If the update payload includes nested collections or nested delta collections, then they MUST be included in the response, as described in Update a Collection of Entities.

Clients should note that requesting a response may be expensive for services that could otherwise efficiently apply updates to a (possibly filtered) collection.

@@ -2797,10 +2802,10 @@

Example 87: the function MostRecentOrder can be bound to any URL that identifies a SampleModel.Customer

-
<Function Name="MostRecentOrder" IsBound="true">
-  <Parameter Name="customer" Type="SampleModel.Customer" />
-  <ReturnType Type="SampleModel.Order" />
-</Function>
+
<Function Name="MostRecentOrder" IsBound="true">
+  <Parameter Name="customer" Type="SampleModel.Customer" />
+  <ReturnType Type="SampleModel.Order" />
+</Function>

Example 88: invoke the MostRecentOrder function with the value of the binding parameter customer being the entity identified by http://host/service/Customers(6)

@@ -2808,10 +2813,10 @@

Example 89: the function Comparison can be bound to any URL that identifies a collection of entities

-
<Function Name="Comparison" IsBound="true">
-  <Parameter Name="in" Type="Collection(Edm.EntityType)" />
-  <ReturnType Type="Diff.Overview" />
-</Function>
+
<Function Name="Comparison" IsBound="true">
+  <Parameter Name="in" Type="Collection(Edm.EntityType)" />
+  <ReturnType Type="Diff.Overview" />
+</Function>

Example 90: invoke the Comparison function on the set of red products

@@ -2837,28 +2842,28 @@

format.

Example 92: given a GET request to http://host/service/Customers('ALFKI'), the service might respond with a Customer that includes the SampleEntities.MostRecentOrder function bound to the entity

-
{
-  "@context": …,
-  "CustomerID": "ALFKI",
-  "CompanyName": "Alfreds Futterkiste",
-  "#SampleEntities.MostRecentOrder": {
-    "title": "Most Recent Order",
-    "target": "Customers('ALFKI')/SampleEntities.MostRecentOrder()"
-  },
-  …
-}
+
{
+  "@context": …,
+  "CustomerID": "ALFKI",
+  "CompanyName": "Alfreds Futterkiste",
+  "#SampleEntities.MostRecentOrder": {
+    "title": "Most Recent Order",
+    "target": "Customers('ALFKI')/SampleEntities.MostRecentOrder()"
+  },
+  …
+}

An efficient format that assumes client knowledge of metadata may omit actions and functions from the payload whose target URL can be computed via metadata following standard conventions defined in OData-URL.

Services can advertise that a function or action is not available for a particular instance by setting its value to null.

Example 93: the SampleEntities.MostRecentOrder function is not available for customer ALFKI

-
{
-  "@context": …,
-  "CustomerID": "ALFKI",
-  "CompanyName": "Alfreds Futterkiste",
-  "#SampleEntities.MostRecentOrder": null,
-  …
-}
+
{
+  "@context": …,
+  "CustomerID": "ALFKI",
+  "CompanyName": "Alfreds Futterkiste",
+  "#SampleEntities.MostRecentOrder": null,
+  …
+}

@@ -2949,17 +2954,17 @@

If-Match header with the latest known ETag value for the entity or collection of entities. The ETag value for a collection as a whole is transported in the ETag header of a collection response.

Example 99: invoke the SampleEntities.CreateOrder action using Customers('ALFKI') as the customer (or binding parameter). The values 2 for the quantity parameter and BLACKFRIDAY for the discountCode parameter are passed in the body of the request. Invoke the action only if the customer’s ETag still matches.

-
POST http://host/service/Customers('ALFKI')/SampleEntities.CreateOrder
-If-Match: W/"MjAxOS0wMy0yMVQxMzowNVo="
-Content-Type: application/json
-
-{
-  "items": [
-    { "product": 4001, "quantity": 2 },
-    { "product": 7062, "quantity": 1 },
-  ],
-  "discountCode": "BLACKFRIDAY"
-}
+
POST http://host/service/Customers('ALFKI')/SampleEntities.CreateOrder
+If-Match: W/"MjAxOS0wMy0yMVQxMzowNVo="
+Content-Type: application/json
+
+{
+  "items": [
+    { "product": 4001, "quantity": 2 },
+    { "product": 7062, "quantity": 1 },
+  ],
+  "discountCode": "BLACKFRIDAY"
+}

@@ -3078,11 +3083,11 @@

Example 103:

-
PATCH /path/service/People(1) HTTP/1.1
-Host: myserver.mydomain.org:1234
-Content-Type: application/json
-
-{ "Name": "Peter" }
+
PATCH /path/service/People(1) HTTP/1.1
+Host: myserver.mydomain.org:1234
+Content-Type: application/json
+
+{ "Name": "Peter" }
  • Resource path relative to the batch request URI.
    • @@ -3238,35 +3243,35 @@ 

    POST /service/$batch HTTP/1.1
-Host: host
-OData-Version: 4.0
-Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
-Content-Length: ###
-
---batch_36522ad7-fc75-4b56-8c71-56071383e77b
-Content-Type: application/http
-Content-ID: 1
-
-GET /service/Employees(0) HTTP/1.1
-Host: host
-Accept: application/json
-
-
---batch_36522ad7-fc75-4b56-8c71-56071383e77b
-Content-Type: application/http
-Content-ID: 2
-
-PATCH /service/Employees(0) HTTP/1.1
-Host: host
-Content-Type: application/json
-Content-Length: ###
-If-Match: $1
-
-{
-   "Salary": 75000
-}
---batch_36522ad7-fc75-4b56-8c71-56071383e77b--
    +
    POST /service/$batch HTTP/1.1
+Host: host
+OData-Version: 4.0
+Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
+Content-Length: ###
+
+--batch_36522ad7-fc75-4b56-8c71-56071383e77b
+Content-Type: application/http
+Content-ID: 1
+
+GET /service/Employees(0) HTTP/1.1
+Host: host
+Accept: application/json
+
+
+--batch_36522ad7-fc75-4b56-8c71-56071383e77b
+Content-Type: application/http
+Content-ID: 2
+
+PATCH /service/Employees(0) HTTP/1.1
+Host: host
+Content-Type: application/json
+Content-Length: ###
+If-Match: $1
+
+{
+   "Salary": 75000
+}
+--batch_36522ad7-fc75-4b56-8c71-56071383e77b--

diff --git a/docs/odata-protocol/odata-protocol.md b/docs/odata-protocol/odata-protocol.md index f9e1b2cd..03700116 100644 --- a/docs/odata-protocol/odata-protocol.md +++ b/docs/odata-protocol/odata-protocol.md @@ -4573,21 +4573,29 @@ Content-Type: application/json ``` If the targeted entity in the payload contains some structural properties, -`PUT` resets all its other structural properties. The following therefore does -not have the desired effect: +`PUT` resets all its other structural properties. The following alternative +payloads both reset the first and last names of the new manager: ```json -PUT http://host/service/Employees(7) -Content-Type: application/json - { "FirstName": "Suzanne", "LastName": "Brown-Johnson", "Manager": { + "@context": "$metadata#$ref", "@id": "Employees(6)", "EmployeeID": 6 } } ``` + +```json +{ + "FirstName": "Suzanne", + "LastName": "Brown-Johnson", + "Manager": { + "EmployeeID": 6 + } +} +``` ::: Clients MAY associate an id with individual nested entities in the diff --git a/odata-protocol/11.4 Data Modification.md b/odata-protocol/11.4 Data Modification.md index 35ff4cdf..cb4133e9 100644 --- a/odata-protocol/11.4 Data Modification.md +++ b/odata-protocol/11.4 Data Modification.md @@ -569,21 +569,29 @@ Content-Type: application/json ``` If the targeted entity in the payload contains some structural properties, -`PUT` resets all its other structural properties. The following therefore does -not have the desired effect: +`PUT` resets all its other structural properties. The following alternative +payloads both reset the first and last names of the new manager: ```json -PUT http://host/service/Employees(7) -Content-Type: application/json - { "FirstName": "Suzanne", "LastName": "Brown-Johnson", "Manager": { + "@context": "$metadata#$ref", "@id": "Employees(6)", "EmployeeID": 6 } } ``` + +```json +{ + "FirstName": "Suzanne", + "LastName": "Brown-Johnson", + "Manager": { + "EmployeeID": 6 + } +} +``` ::: Clients MAY associate an id with individual nested entities in the