Skip to content

Tutorial 02 07 Single Entity Endpoints

Jump to bottom
mattl91 edited this page Mar 3, 2023 · 12 revisions

Harmony Core Logo

Single Entity Endpoints

A "single entity" endpoint enables you to get a single instance of an entity via its primary key. For example, it enables you to get one customer, one order, etc.

VIDEO: Creating a Basic Solution

Here is an example of a single entity endpoint URL:

https://localhost:8086/odata/v1/Customers(CustomerNumber=1)

Enabling Single Entity Endpoints

To generate single entity endpoints, you must set the Enable primary key endpoints option:

  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 primary key endpoints option, and double-click it.

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

Generating the Code

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

  2. Regenerate generated 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

Enabling this option causes an additional GET method to be generated in each of your controller classes. Here is what the new method looks like in Services.Controllers\CustomersController.dbl:

{HttpGet("Customers(CustomerNumber={aCustomerNumber})")}
{Produces("application/json")}
{ProducesResponseType(^typeof(Customer),StatusCodes.Status200OK)}
{ProducesResponseType(StatusCodes.Status404NotFound)}
{EnableQuery(MaxExpansionDepth=4)}
;;; <summary>
;;; Get a single Customer by primary key.
;;; </summary>
;;; <param name="aCustomerNumber">Customer number</param>
;;; <returns>Returns a SingleResult indicating the status of the operation and containing any data that was returned.</returns>
public method GetCustomer, @SingleResult<Customer>
    {FromODataUri}
    required in aCustomerNumber, int
proc
    mreturn new SingleResult<Customer>(_DbContext.Customers.AsNoTracking().FindQuery<Customer>(_DbContext, aCustomerNumber))
endmethod

Notice that the method is decorated with an HttpGet attribute:

{HttpGet("Customers(CustomerNumber={aCustomerNumber})")}

In this case, the attribute specifies that a parameter named CustomerNumber must be provided to access the endpoint, so the URL will look something like this:

https://localhost:8086/odata/v1/Customers(CustomerNumber=aCustomerNumber)

The method accepts a single parameter named aCustomerNumber, and you will notice that this corresponds to the value specified in the HttpGet attribute. This means that the value passed via the CustomerNumber parameter in the URL will be fed into the method by the corresponding method parameter.

You will also notice that the method returns a customer entity (record) that matches that ID. This is signified by the return value of the method, in this case @SingleResult<Customer>.

You will find similar code in the other controller classes.

Building the Code

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

  2. 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 Feature

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

Once again you should see the console window appear with a message confirming that your service is running.

  1. Open your browser and go to the API documentation page:

You should see that the single entity endpoints are now documented:

API Docs with Single Entity Endpoints

  1. Now go to the single customer endpoint, specifying the value for the primary key of an existing customer record:

You should see a JSON response that includes the full record for the specified customer.

  1. Do the same with the single entity endpoints for the other four entity types:

Stop the Service

  1. When you are done with your testing, stop the self-hosting application.

Suppressing Single Entity Endpoints

Enabling single entity endpoints adds endpoints to all your code-generated OData controllers, but it is possible to prevent the generation of these endpoints for certain structures. This capability is documented in Structure-Specific Endpoint Control.

Next topic: OData Query Support

Clone this wiki locally