Tutorial 02 08 OData Query Support

OData Query Support

One of the most powerful features of OData services is the ability for consumers to supply query expressions in the URL, and for the OData (and in the case of Harmony Core, the underlying Entity Framework provider) to respond to and leverage those queries when accessing the underlying data.

OData queries enable the consumers of a REST API to use

• $select to specify which properties of entities are to be returned.
• $filter to build logical expressions to restrict the entities to be returned.
• $orderby to specify ordering criteria for collections of entities.
• $top to constrain the number of entities returned.
• $skip (in conjunction with $top) to access data "pages" with a size of their choosing.

By using one or more of these capabilities, it is possible for client applications to focus in on exactly the data they need and to obtain that data with optimal performance—all without the developer of a service having to predict the needs of the consumers of the REST API.

Without the capabilities of OData queries, a large-scale REST API might need hundreds of endpoints, with each endpoint designed for a specific use case. With OData queries, APIs typically expose significantly fewer endpoints and are therefore easier and faster to build and maintain and are less prone to errors.

Enabling OData Query Support

In the Harmony Core environment, each of the query features mentioned above can be individually enabled, as necessary. This is done by setting options in the Harmony Core CLI tool:

1. At a Windows prompt, move to the directory with your Harmony Core solution, and type harmonycore gui. Then, when the GUI for the Harmony Core CLI tool opens, go to the OData screen, scroll down to the Enable OData select option, and double-click it.

2. In the "Enter new value" screen, click the diamond icon to the right of Enable OData select. (The diamond will change to a checkmark.) Then click OK.

3. Repeat the process for the following options: Enable OData filters, Enable OData orderby, Enable OData top, and Enable OData skip.

Generating the Code

4. Save the settings you made by selecting File > Save from the menu.

5. Regenerate code for your solution by selecting Codegen > Regen from the menu.

When code generation is finished, a message will list the files that were generated.

What Changed

The OData query options do not cause any additional files to be generated, but they do cause additional content to be generated into various files:

• Additional OData configuration options are specified in the code of the Startup class.
• Additional OData query capabilities are now enabled and active in the API documentation.

Building the Code

6. In Visual Studio, select Build > Rebuild Solution from the menu.

7. Check the Output window, you should see something like this:

   1>------ Rebuild All started: Project: Repository, Configuration: Debug Any CPU ------
   2>------ Rebuild All started: Project: Services.Models, Configuration: Debug Any CPU ------
   3>------ Rebuild All started: Project: Services.Controllers, Configuration: Debug Any CPU ------
   4>------ Rebuild All started: Project: Services.Isolated, Configuration: Debug Any CPU ------
   5>------ Rebuild All started: Project: Services, Configuration: Debug Any CPU ------
   6>------ Rebuild All started: Project: Services.Host, Configuration: Debug Any CPU ------
   ========== Rebuild All: 6 succeeded, 0 failed, 0 skipped ==========
   

Testing the Changes

8. In Visual Studio, press F5 (Start Debugging) to start the self-hosting application.

9. Try using $select with any GET query, and try using $filter, $orderby, $top and $skip with any endpoint that returns multiple entities. For example:

• Get the customer number and name for customer 1:

  • https://localhost:8086/odata/v1/Customers(CustomerNumber=1)?$select=CustomerNumber,Name

• Get all customers in the state of Washington:

  • https://localhost:8086/odata/v1/Customers?%24filter=State+eq+'WA'

• Get all customers ordered by highest credit limit:

  • https://localhost:8086/odata/v1/Customers?$orderby=CreditLimit+desc

• Get the first two customers:

  • https://localhost:8086/odata/v1/Customers?$top=2

• Get all customers except the first two:

  • https://localhost:8086/odata/v1/customers?$skip=2

Stop the Service

10. When you are done testing, stop the self-hosting application.

---

Next topic: Alternate Key Endpoints

---