OData Entity Design: Additional field for query

Question

We are currently designing an OData compliant entity data model that will be consumed by a mobile application. The team is divided into two; the backend developers providing the OData services and the front-end developers consuming these services.

One point of disagreement between front-end and backend developers is about the design of our main entity. From the front-end perspective, it should look like:

Order:
Order ID
Order Type
Assigned To
Customer ID
Price
Currency
etc...

The Order object will be queried with such URLs:

http://SERVICE_ROOT_URL/Orders?$filter=Order_Type eq 'Inquiry' or Order_Type eq 'Quotation'
http://SERVICE_ROOT_URL/Orders?$filter=Order_Type eq 'Inquiry' and Assigned_To eq 'James7'

The backend developers are willing to add a new field to the Order entity and use this field to understand what the user is querying. Let's name this new field Request Code. With the request code field, the queries will look like:

http://SERVICE_ROOT_URL/Orders?$filter=Request_Code eq '0022' // The orders requiring approval and the current user can approve them
http://SERVICE_ROOT_URL/Orders?$filter=Request_Code eq '0027' // The orders with the open status

Basically, the Request Code is not an actual part of the entity but artificial. It just adds some intelligence so that the querying becomes easier for the backend. This way, the backend will only support those queries that have this request code. The Request Code is also planned to be used in the update scenario, where the front-end is expected to pass the Request Code when updating the Order entity. This way, the backend will know which fields to update by looking at the request code.

I am in the front-end and I don't think Request Code should be included in the model. It makes the design encrypted and takes away the simplicity of the OData services. I also don't see any added value other than making things easier at the backend.

Is this a common practice in OData Services design?

Answer 1

To me, this extra property is inappropriate. It adds an extra layer of semantics on top of OData; which requires extra understanding and extra coding to deal with. It only adds accidental complexity, it leaks a backend implementation detail to its public API.

The OData querying interface should be enough to describe most situations. When it's not enough, you can create service operations to describe extra business semantics.

So, for example, this:

/Orders?$filter=Request_Code eq '0022' // The orders requiring approval and the current user can approve them
/Orders?$filter=Request_Code eq '0027' // The orders with the open status

Could become this:

/GetOrdersRequiringApprovalFromUser
/GetOpenOrders

Also, for the update logic, OData already supports updating individual properties.

So, in sum, don't invent another protocol on top of OData. Use what it provides.