Tutorial 02 18 Adding Delete Endpoints

Adding Delete Endpoints

When enabled, deleting an entity is one of the most simple operations, because all that is required is an HTTP DELETE method to be executed against a specific entity endpoint; no data is required in the request body, and no additional HTTP headers are required.

Enabling Delete Endpoints

To generate endpoints that allow clients to delete entities via HTTP DELETE operations you must enable the ENABLE_DELETE option:

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

   set ENABLE_DELETE=-define ENABLE_DELETE
   

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.

5. Look for the word DONE to indicate that all code generation tasks completed successfully.

What Changed

Enabling the ENABLE_DELETE option causes an additional endpoint method to be added to each of the generated OData Controller classes. The new method looks something like this:

{ODataRoute("(CustomerNumber={aCustomerNumber})")}
{ProducesResponseType(StatusCodes.Status204NoContent)}
{ProducesResponseType(StatusCodes.Status404NotFound)}
{HttpDelete}
;;; <summary>
;;; Delete a customer.
;;; </summary>
;;; <param name="aCustomerNumber">Customer number</param>
;;; <returns>Returns an IActionResult indicating the status of the operation and containing any data that was returned.</returns>
public method DeleteCustomer, @IActionResult
    {FromODataUri}
    required in aCustomerNumber, int
proc
    ;;Get the customer to be deleted
    data customerToRemove = _DbContext.Customers.Find(aCustomerNumber)

    ;;Did we find it?
    if (customerToRemove == ^null)
        mreturn NotFound()

    ;;Delete and commit
    _DbContext.Customers.Remove(customerToRemove)
    _DbContext.SaveChanges()

    mreturn NoContent()

endmethod

The sample code above was taken from CustomersController.dbl, and as you can see the code accepts a single parameter, which is the primary key value for the entity to be deleted.

Note that the parameter is decorated with an attribute {FromODataUri}, indicating that the data must be provided via a URL prarmeter of the HTTP request.

If the entities primary key included multiple segments then additional parameters would be present.

Notice that on successful completion the code returns a value of NoContent(), which will result in an HTTP 204 No Content response to the client.

You will find similar new code in all of your other controllers.

If you are generating Postman Tests then a new DELETE request is added to the folder for each entity type, but you will need to re-import the newly generated tests into Postman. The instructions will walk you through doing this later.

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.

It is not possible to test the functionality of the new endpoints using a web browser, because the functionality to be tested involves issuing an HTTP DELETE request. Our tool of choice for issuing PATCH requests is Postman.

9. Start Postman and close any request tabs that may be open.

10. Select File > Import from the Postman menu.

11. In the IMPORT dialog, click the Upload Files button.

12. Browse to your main solution folder, select the PostManTests.postman_collection.json file, then click the Open button.

13. Back in the IMPORT dialog, click the Import button.

14. In the COLLECTION EXISTS dialog, click the Replace button.

Postman will now re-load the tests in the Harmony Core Sample API collection, and you will notice that the total number of tests increases.

15. Open the Customer Tests folder and select the DEL Delete customer request.

You will notice that:

• The HTTP method is set to DELETE.
• The URL is set to {{ServerBaseUri}}/Customers(CustomerNumber=123)

16. Change the value of the CustomerNumber parameter in the URL to 1 then click the big blue Send button.

You should see a 204 No Content response, indicating that the entity was deleted.

17. Click the big blue Send button again.

Now you should see a 404 Not Found response because you are trying to delete an entity that has already been deleted!

Stop the Service

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

Suppressing Delete Endpoints

Enabling delete 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: Basic Service Tutorial Review

---