{"id":5299,"date":"2023-06-09T00:36:03","date_gmt":"2023-06-09T07:36:03","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/odata\/?p=5299"},"modified":"2023-06-09T00:36:03","modified_gmt":"2023-06-09T07:36:03","slug":"deep-insert-support-in-odata-web-api","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/odata\/deep-insert-support-in-odata-web-api\/","title":{"rendered":"Deep insert support in OData Web API"},"content":{"rendered":"

Background<\/h3>\n

In OData Web API 7.7.0<\/code>, we added support for deep insert.\u00a0<\/span>In deep insert, we create an object and its related items or link existing items in a single request.<\/span><\/p>\n

This blog post is a continuation of Bulk Operations Support in OData Web API<\/a>. In that blog post, we explained how to use ODataAPIHandler<\/code> and ODataAPIHandlerFactory<\/code> classes. We will not repeat that in this blog post. Bulk update and deep insert share the same ODataAPIHandler<\/code> and ODataAPIHandlerFactory<\/code> classes.<\/p>\n

In the following sections, we will cover how deep insert is implemented in OData Web API<\/code> and the things that the developer needs to do to use it in their OData service.<\/span><\/p>\n

Controller<\/h3>\n
[ODataRoute(\"Customers\")]\r\n[HttpPost]\r\n[EnableQuery]\r\npublic IActionResult Post([FromBody] Customer customer)\r\n{\r\n    var handler = new CustomerAPIHandler();\r\n\r\n    handler.DeepInsert(customer, Request.GetModel(), new APIHandlerFactory(Request.GetModel()));\r\n\r\n    return Created(customer);\r\n}<\/code><\/pre>\n
 For the controller action to handle deep insert, the HttpPost<\/code> attribute must be applied together with the EnableQuery<\/code> attribute to ensure<\/span> that the response has the navigation properties expanded to the level of the request.<\/p>\n
According to the OData spec<\/span><\/a> \u201c<\/span>On success, the service MUST create all entities and relate them. If the service responds with\u202f<\/span><\/em>201 Created<\/em><\/span>, the response MUST be expanded to at least the level that was present in the deep-insert request<\/span><\/em>.<\/span>\u201d\u00a0<\/span>\u00a0<\/span><\/p>\n
IExpandQueryBuilder interface<\/h3>\n
IExpandQueryBuilder<\/code> is the base interface for generating an $expand<\/code> query parameter from a payload. Currently we only have one method in the interface.<\/p>\n
public interface IExpandQueryBuilder\r\n{\r\n    string GenerateExpandQueryParameter(object value, IEdmModel model);\r\n}<\/code><\/pre>\n
The default implementation of the IExpandQueryBuilder<\/code> interface is the ExpandQueryBuilder<\/code> class.<\/p>\n
public class ExpandQueryBuilder : IExpandQueryBuilder\r\n{\r\n    \/\/\/ <inheritdoc \/>\r\n    public virtual string GenerateExpandQueryParameter (object value, IEdmModel model)\r\n    {\r\n        return expandString;\r\n    }\r\n}<\/code><\/pre>\n
This is the class that makes it possible to expand the navigation properties in the response. The class takes the payload object and generates an expand query parameter which is then appended to the HttpRequest<\/code>.<\/p>\n
The GenerateExpandQueryParameter<\/code> method takes a payload object<\/code> and IEdmModel<\/code> and returns an $expand<\/code> string.<\/p>\n
For example: If we have an Employee<\/code> object with nested Friends<\/code> and NewFriends<\/code> as below:<\/p>\n
Employee employee = new Employee\r\n{\r\n\u00a0\u00a0\u00a0 ID = 1,\r\n\u00a0\u00a0\u00a0 Friends = new List<Friend>\r\n\u00a0\u00a0\u00a0 {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 new Friend\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Id = 1001,\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Orders = new List<Order> { new Order { Id = 10001 } }\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }\r\n\u00a0\u00a0\u00a0 },\r\n\u00a0\u00a0\u00a0 NewFriends = new List<NewFriend>\r\n\u00a0\u00a0\u00a0 {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 new NewFriend\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 {\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Id = 1001,\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 NewOrders = new List<NewOrder> { new NewOrder { Id = 10001 } }\r\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }\r\n\u00a0\u00a0\u00a0 }\r\n};<\/span><\/pre>\n
We return an expand string: $expand=Friends($expand=Orders),NewFriends($expand=NewOrders)<\/code><\/p>\n
In the above block of code, Friends<\/code> property has nested Orders<\/code> property and NewFriends<\/code> property has nested NewOrders<\/code> property.<\/p>\n
The customer can provide their own custom implementation of IExpandQueryBuilder<\/code> and inject it into the dependency injection container as follows:<\/span><\/p>\n
In the Startup.cs<\/strong><\/p>\n
public void ConfigureServices(IServiceCollection services)\r\n{\r\n    services.AddOData();\r\n    services.AddMvc(options =>\r\n    {\r\n        options.EnableEndpointRouting = false;\r\n    });\r\n\r\n    services.AddSingleton<IExpandQueryBuilder, CustomExpandQueryBuilder>();\r\n}<\/code><\/pre>\n
The CustomExpandQueryBuilder<\/code> should implement the IExpandQueryBuilder<\/code> interface or alternatively subclass the ExpandQueryBuilder<\/code> class and override the virtual methods. <\/span><\/p>\n
OData API Handler<\/h3>\n
In the controller method above, we initialized a CustomerAPIHandler<\/code> class.<\/p>\n
The ODataAPIHandler<TStructuralType><\/code> has a default implementation of DeepInsert<\/code> method which can be used.<\/p>\n
public abstract class ODataAPIHandler<TStructuralType>: IODataAPIHandler where TStructuralType : class\r\n{\r\n    \/\/ Other  methods\r\n    public virtual void DeepInsert(TStructuralType resource, IEdmModel model, ODataAPIHandlerFactory apiHandlerFactory)\r\n    {\r\n        if (resource == null || model == null)\r\n        {\r\n            return;\r\n        }\r\n\r\n        \/\/ Other code\r\n\r\n        CopyObjectProperties(resource, model, this, apiHandlerFactory);\r\n    }\r\n    \r\n    internal static void CopyObjectProperties(object resource, IEdmModel model, IODataAPIHandler apiHandler, ODataAPIHandlerFactory apiHandlerFactory)\r\n    {\r\n        if (resource == null || model == null || apiHandler == null)\r\n        {\r\n            return;\r\n        }\r\n        \/\/ Other code\r\n    }\r\n}\r\n<\/code><\/pre>\n
We can override the DeepInsert<\/code> method and add our custom implementation.<\/p>\n
public class CustomerAPIHandler : ODataAPIHandler<Customer>\r\n{\r\n    public override void DeepInsert(TStructuralType resource, IEdmModel model, ODataAPIHandlerFactory apiHandlerFactory)\r\n    {\r\n        base.DeepInsert(resource, model, apiHandlerFactory);\r\n    }\r\n}<\/code><\/pre>\n
Query options<\/h3>\n
We can add query options in our POST<\/code> request. If there is an expand query parameter in the query options, we will not generate $expand<\/code> query parameters using the ExpandQueryBuilder<\/code>.<\/strong><\/p>\n
POST http:\/\/localhost:6285\/odata\/Customers?$expand=Orders\r\nContent-Type: application\/json\r\n{\r\n    \"Id\": 1,\r\n    \"Name\": \"Customer1\",\r\n    \"Orders\": [\r\n        {\r\n            \"@odata.id\": \"Customers(3)\/Orders(1005)\"\r\n        },\r\n        {\r\n            \"Id\": 2000,\r\n            \"Price\": 200,\r\n            \"Quantity\": 90\r\n        }\r\n    ]\r\n}\r\n<\/code><\/pre>\n
Below will be the response:<\/p>\n
{\r\n    \"@odata.context\": \"http:\/\/localhost:6285\/odata\/$metadata#Customers(Orders())\/$entity\",\r\n    \"Id\": 1,\r\n    \"Name\": \"Customer1\",\r\n    \"Age\": 0,\r\n    \"Orders\": [\r\n        {\r\n            \"Id\": 1005,\r\n            \"Price\": 40,\r\n            \"Quantity\": 15\r\n        },\r\n        {\r\n            \"Id\": 2000,\r\n            \"Price\": 200,\r\n            \"Quantity\": 90\r\n        }\r\n    ]\r\n}<\/code><\/pre>\n
 <\/p>\n","protected":false},"excerpt":{"rendered":"
Background In OData Web API 7.7.0, we added support for deep insert.\u00a0In deep insert, we create an object and its related items or link existing items in a single request. This blog post is a continuation of Bulk Operations Support in OData Web API. In that blog post, we explained how to use ODataAPIHandler and […]<\/p>\n","protected":false},"author":20598,"featured_media":3253,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1,117],"tags":[],"class_list":["post-5299","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-odata","category-webapi"],"acf":[],"blog_post_summary":"
Background In OData Web API 7.7.0, we added support for deep insert.\u00a0In deep insert, we create an object and its related items or link existing items in a single request. This blog post is a continuation of Bulk Operations Support in OData Web API. In that blog post, we explained how to use ODataAPIHandler and […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts\/5299","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/users\/20598"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/comments?post=5299"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/posts\/5299\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/media\/3253"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/media?parent=5299"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/categories?post=5299"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/odata\/wp-json\/wp\/v2\/tags?post=5299"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}