Tutorial 02 18 Adding Delete Endpoints

Adding Delete Endpoints

When enabled, deleting an entity is one of the simplest 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 enable clients to delete entities via HTTP DELETE operations, you must set the Enable DELETE endpoints option in the Harmony Core CLI tool:

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 DELETE endpoints option, and double-click it.

2. In the "Enter new value" screen, click the diamond icon to the right of Enable DELETE 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

Enabling the Enable DELETE endpoints option causes an additional endpoint method to be added to each of the generated OData controller classes. The new method looks like this:

        {HttpDelete("Customers(CustomerNumber={aCustomerNumber})")}
        {ProducesResponseType(StatusCodes.Status204NoContent)}
        {ProducesResponseType(StatusCodes.Status404NotFound)}
        ;;; <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 the following:

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

• If the entity's primary key included multiple segments, additional parameters would be present.

• 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 the other controllers.

If you are generating Postman tests, 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. You'll do this in one of the steps below.

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.

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 DELETE requests is Postman.

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

9. Select File > Import from the Postman menu or click the Import button.

10. In the Import dialog, click the Choose Files button, which opens the Open dialog.

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

12. On the Import Elements tab, click the Import button.

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

Postman will now reload the tests in the "Harmony Core Sample API" collection. Notice that the total number of tests increases.

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

Note the following:

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

15. Change the value of the CustomerNumber parameter in the URL to 1, and then click the blue Send button. You should see a 204 No Content response, indicating that the entity was deleted.

16. Click the 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

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

Suppressing Delete Endpoints

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

---