Tutorial 02 09 Alternate Key Endpoints

Alternate Key Endpoints

In addition to generating OData endpoints that allow entities to be accessed by their primary key, which usually results in a single entity being returned, it is also possible to generate endpoints that access data based on alternate keys that may be defined for each entity type.

Some of these endpoints may result in a single entity being returned. For example, you might access a customer entity via a key associated with the customer's main office telephone number. Other endpoints may result in multiple entities being returned, for example via a key that enables you to access all customers in a particular city or state.

Enabling Alternate Key Endpoints

To generate endpoints that expose entities via alternate keys, you must set the Enable alt 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 alt endpoints option, and double-click it.

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

Generating the Code

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

4. Generate code for your solution by selecting Codegen > Regen from the menu.

When code generation is finished, a message lists the files that were generated. Click OK to close the message.

What Changed

No additional files are generated as a result of this change. Instead, this option enables additional areas of code in the template files being used, which results in the generation of additional code into several source files:

• A new GET method (endpoint) is added in the controller classes, one for each alternate key.

• New alternate key endpoints will appear in the API documentation.

Here is an example of an alternate key endpoint method (from CustomersController.dbl):

{HttpGet("Customers(State={aState})")}
{Produces("application/json")}
{ProducesResponseType(^typeof(IEnumerable<Customer>),StatusCodes.Status200OK)}
{ProducesResponseType(StatusCodes.Status404NotFound)}
{EnableQuery(MaxExpansionDepth=4)}
;;; <summary>
;;; Get customers by alternate key key State.
;;; </summary>
;;; <param name="aState">State</param>
;;; <returns>Returns an IActionResult indicating the status of the operation and containing any data that was returned.</returns>
public method GetCustomersByState, @IActionResult
    {FromODataUri}
    required in aState, String
proc
    data result = _DbContext.Customers.AsNoTracking().FindAlternate("State",aState)
    if (result == ^null)
        mreturn NotFound()

    mreturn Ok(result)
endmethod

Building the Code

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

6. 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 New Functionality

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

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

You should be able to interact with the additional endpoints. The new functionality comes in the form of additional GET methods in controllers. For example, if you are working with the Harmony Core sample repository and data, these are some of the additional operations that should now be available:

8. Get all customers in the state of Washington:

   • https://localhost:8086/odata/v1/customers(State='WA')

9. Get all items with white flowers:

   • https://localhost:8086/odata/v1/Items(FlowerColor='white')

10. Get all vendors with a payment terms code of '30':

    • https://localhost:8086/odata/v1/Vendors(PaymentTermsCode='30')

Stop the Service

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

Suppressing Alternate Key Endpoints

Enabling alternate key 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: Expanding Relations

---