Tutorial 02 10 Individual Property Endpoints
In addition to returning entire entities (a customer entity, for example), the generated OData controllers can be configured to expose endpoints that return the individual properties of an entity. For example, a developer could retrieve only the name of a customer, or only the price of an inventory item.
Individual property endpoints always operate using the primary key of an entity, and even when enabled, will only be generated for structures with unique primary keys.
In many cases, supporting this feature allows client developers to target exactly the data they need, and obtain that data with minimal overhead and optimal performance; the endpoints are very efficient and fast because they return such a small amount of data.
An example of the data returned by one of these endpoints looks like this:
{
"@odata.context": "https://localhost:8086/odata/$metadata#Customers(8)/Name",
"value": "Broadway Nursery"
}
The data returned is fairly minimal, but it can be minimized even more by suppressing the OData metadata that is being returned. Doing so would result in data that looks like this:
{
"value": "Broadway Nursery"
}
But there is another option that is even more efficient in terms of the size of the data returned. By appending /$value to the property endpoint URL it is possible to request that only the raw value of the data is returned, like this:
Broadway Nursery
To generate endpoints that expose individual properties, you must enable the ENABLE_PROPERTY_ENDPOINTS option:
-
Edit
regen.batand remove the rem comment from the beginning of the line, like this:set ENABLE_PROPERTY_ENDPOINTS=-define ENABLE_PROPERTY_ENDPOINTS
-
Save your changes to regen.bat.
-
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 .. -
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.
The ENABLE_PROPERTY_ENDPOINTS option results in the generation of a web service endpoint method for every non-primary-key field in each structure. For structures with a large number of fields this can represent a significant amount of code being added to the controller classes, so to maintain code readability the new individual property endpoint methods are generated into separate source files in the Services.Controllers project folder.
The names of these new source files will be the same as the names of all of your existing controller class source files, but suffixed with PropertyEndpoints. So for example, if you generate controllers for a structure named CUSTOMERS you will now see the following source files in the Services.Controllers project folder:
CustomersController.dbl
CustomersControllerPropertyEndpoints.dbl
The newly generated files use a technique called partial classes which means that the code from these pairs of source files is essentially added together by the compiler, the additional code in the new source files simply adds to the code in the existing files.
Here is an example of an individual property endpoint method:
{HttpGet("Customers({key})/Name")}
{Produces("application/json")}
{ProducesResponseType(StatusCodes.Status200OK)}
{ProducesResponseType(StatusCodes.Status404NotFound)}
;;; <summary>
;;; Get the Name property of a single Customer, by primary key.
;;; </summary>
;;; <param name="key">Customer name</param>
;;; <returns>
;;; Returns a string containing the value of the requested property.
;;;</returns>
public method GetName, @IActionResult
{FromODataUri}
required in key, int
proc
data result = _DbContext.Customers.Find(key)
if (result==^null)
mreturn NotFound()
mreturn OK(result.Name)
endmethod
As you can see from the sample code, the entity framework provider (represented by DbContext) is used to obtain the full entity requested, but only the value of a single property (Name, in this case) is returned to the consumer of the REST API.
-
Right-click on the
Services.Controllersproject and selectAdd > Existing Item. -
Select and add all of the new source files that end with 'PropertyEndpoints.dbl' (5 files).
CustomersControllerPropertyEndpoints.dbl ItemsControllerPropertyEndpoints.dbl OrderItemsControllerPropertyEndpoints.dbl OrdersControllerPropertyEndpoints.dbl VendorsControllerPropertyEndpoints.dbl
-
Select
Build > Rebuild Solutionfrom the Visual Studio menu. -
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 ==========
- 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.
- First off, if you check the API documentation, you will see a large number of new endpoints, one for each property of each entity type (except for primary key segments).
If you are working with the Harmony Core sample repository and data, these are some of the additional operations that should now be available:
-
Get the name for customer 1
-
Get the name for customer 1, raw data only
- When you are done with your testing, stop the self-hosting application.
Enabling individual property 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: Expanding Relations