Part 03 – OData v4 in ASP.NET WebApi – Service Document

This is a series of blogs detailing my introduction to using OData v4 with C# and ASP.NET WebApi.

What is an OData Service

An OData Service is where you expose your data to the client. An OData URL will always start http://host/Service. It is possible to expose multiple OData Services on the same host which may carry out the same functionality but with different restrictions.

What is a Service Document

A Service Document lists the OData Entities, Function Imports, Singletons and links to other Service Documents defined in your Entity Data Model. It is always returned from the root URL of the service.

Viewing a Service Document

Before I build my own OData service, let’s look at a demo service provided on the website. There is a demo service called Trip Pin which can manage people’s trips. You can read about the demo service here.

Using a tool like Postman we can send RESTful requests and view the responses.

Issuing a GET request to we get the following JSON response returned.

The Service Document has at least a @odata.context string and an array called value. The @odata.context is a URL to the MetaData Document which I will explain in a future blog. The value array returns a list of all the Entities, Function Imports, Singletons and links to other Service Documents defined. In addition you may also see a Title value containing a human readable title for the object.

The example above returned five entities called “People”, “Airlines”, “Airports”, “NewComePeople” and “Me”. Entities are instances of Entity Types. You can think of an Entity Type like C# Class when the type is EntitySet or Singleton. Not shown are any Annotations which may also be included.

In order to get more detailed information for an individual entity to enable clients to interact with the service we need to view the MetaData document. The response above includes a link to the metadata document to help code generators or clients navigate the service.

In the next blog we will look at the MetaData document.