Tutorial 02 07 Single Entity Endpoints

Single Entity Endpoints

Single entity endpoints allow you to a single instance of an entity at a time, via its primary key. For example, "one customer", "one order", etc.

Here is an example of a single entity endpoint URL:

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

Enabling Single Entity Endpoints

To generate endpoints that expose a single entity, by primary key, you must enable the ENABLE_GET_ONE option:

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

   set ENABLE_GET_ONE=-define ENABLE_GET_ONE
   

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
   

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

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.

{ODataRoute("(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 an ODataRoute attribute decorates the method

{ODataRoute("(CustomerNumber={aCustomerNumber})")}

This time the attribute specifies that a parameter named CustomerNumber must be provided in order 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 ODataRoute 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 notice that the method also 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 all of your other controller classes.

Building the Code

5. Select Build > Rebuild Solution from the Visual Studio 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 Feature

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.

8. Open your browser and go to the API documentation page:
   • https://localhost:8086/api-docs/index.html

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

If you want to, try opening up the API documentation and trying out one of the new operations directly from the documentation. Or, continue in the browser for now.

9. Now go to the single customer endpoint, specifying the value for the primary key of an existing customer record:
   • https://localhost:8086/odata/v1/Customers(7)

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

10. You should also be able to do the same with the "single entity" endpoints for the other four entity types:

    • https://localhost:8086/odata/v1/Items(17)
    • https://localhost:8086/odata/v1/Orders(143)
    • https://localhost:8086/odata/v1/OrderItems(3,1)
    • https://localhost:8086/odata/v1/Vendors(40)

Stop the Service

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

Suppressing Single Entity Endpoints

Enabling single entity 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: OData Query Support

---