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, usually resulting in a single entity being returned, it is also possible to generate endpoints that access data based on any 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 their main office telephone number. Other endpoints may result in multiple entities being returned, for example via a key allowing 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 enable the ENABLE_ALTERNATE_KEYS option:

1. Edit regen.bat and remove the rem comment from the beginning of the line, like this:

   set ENABLE_ALTERNATE_KEYS=-define ENABLE_ALTERNATE_KEYS
   

Generating the Code

2. Save your changes to regen.bat.

3. If you don't already have a command prompt open in the solution folder, use the Tools > Command Prompt (x64) menu option to open a Windows command prompt, and type the following command:

   cd ..
   

4. Type the following command to regenerate your code:

   regen
   

5. As the batch file executes you will see various messages confirming which source files are being generated. Look for the word DONE to indicate that all code generation tasks completed successfully.

What Changed

No additional files will be generated as a result of this change; the option enables additional areas of code in the template files being used, in turn generating additional code into several source files:

• A new get method (endpoint) will be 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, taken from CustomersController.dbl:

{ODataRoute("(State={aState})")}
{Produces("application/json")}
{ProducesResponseType(^typeof(ODataValue<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

6. Select Build > Rebuild Solution from the Visual Studio 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 New Functionality

8. 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 Coree sample repository and data, these are some of the additional operations that should now be available:

9. Get all customers in the state of Washington.

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

10. Get all items with white flowers.

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

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

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

Stop the Service

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

Suppressing Alternate Key Endpoints

Enabling alternate key endpoints adds endpoints to all of 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: Individual Property Endpoints

---