Before we can learn about Addressing Entities in OData, we have to lay the ground work for all OData commanding including queries. We will first detail and demonstrate the Uniform Resource Identifier or URI and then look at a URI for OData.
What is a URI?
An URI is a string that is used to identify a name(URN) or a location to a resource( URL). The URN works like a name of a person or a business name where the URL functions like the physical address of a person or business.
The following are two examples of URI's
As you can see the two URI's are both OData URI's. The first is called the Service Root URI and the second is an OData query URI that us requesting the first two Products that are associated to Category 1 returned in alphabetical order.
Service Root URI
Every OData call must include the Service Root URI to interact with an OData feed. Think of the Service Root URI as the location of the OData feed. It represents the HTTP listener that will do the work on the behalf of the consumer of the OData feed based on the URI past the root and the HTTP Verb or Command sent.
You may discover that some OData Service Root URI's do not end with svc. This can be accomplished with routing the request as shown in Ron Jacob's blob post here.
Resource Path of the OData URI
The Resource Path of OData request URI functions as the resource locator from the OData consumer. It can be a request to any of the following resources of the OData protocol:
- Single Entity (Baseball Player)
- Collection of Entities (Baseball Players from a team and year)
- Entity relationship between multiple Entities (Batting Statistics for a specific Baseball Player)
- A Property of an Entity (Last Name of a Baseball Player)
- Service Operation
- Other resources
Query Options of the OData URI
We will work through many of the Query options during this blog series. Know that all Query Options in OData request URI's specify three types of information:
- System Query Options – we will explore this type in detail during this series.
- Custom Query Options – extension point for server specific information. The Custom Query Option is always passed as a name/value pair.
- Service Operation Parameters – used to reference a call Service Operations that reside on the OData feed.
Addressing single or collections of entities located in an OData feed is akin to the FROM clause of a SQL SELECT statement along with JOINs. By allowing associations between Entities an OData request URI can reach far and wide inside the OData feed to request any shape and collection of data.
The following grammar are the rules that cover all entity query scenarios: single Entity, collection of Entities or single Property of Entity.
The areas of the OData request
|Collection||The Collection will cover either a requested Collection of Entities or from a Service Collection which returns a Collection of Entities.|
|KeyPredicate||A predicate that identifies the value(s) of the key Properties of an Entry. If the Entry has a single key Property the predicate may include only the value of the key Property. If the key is made up of two or more Properties, then its value must be stated using name/value pairs. More precisely, the syntax for a KeyPredicate is shown by the following figure.|
|NavPropSingle||The name of a Navigation Property defined by the Entry associated with the prior path segment. The Navigation Property must identify a single entity (that is, have a "to 1" relationship).|
|NavPropCollection||Same as NavPropSingle except it must identify a Collection of Entries (that is, have a "to many" relationship).|
|ComplexType||The name of a declared or dynamic Property of the Entry or Complex Type associated with the prior path segment.|
|Property||The name of a declared or dynamic Property of the Entry or Complex Type associated with the prior path segment.|
We will be looking at many ways to query and shape the data returned from an OData feed in future blog posts. Stay tuned and hope you are enjoying the series. I am working to catch up also.