Add and Protect CRUD Web API Endpoints

• Jun 19, 2024
• 3 minutes to read

This topic describes how to create endpoints in a Web API Service application. See the following topics for information on how to create a project with the Web API:

• Create a New Application with the Web API
• Add a Web API Project to an Existing Solution
• Add the Web API Service to a Blazor Server Project

Create Endpoints for Business Objects

In the Startup.cs file, add or find the services.AddXafWebApi method call and use the BusinessObject method to create endpoints for business objects. The following code creates endpoints for the ApplicationUser and Contact business objects:

File: MySolution.WebApi\Startup.cs (MySolution.Blazor.Server\Startup.cs)

C#

using MySolution.Module.BusinessObjects;
// ...
namespace MySolution.WebApi {
    public class Startup {
        // ...
        public void ConfigureServices(IServiceCollection services) {
            // ...
            services.AddXafWebApi(Configuration, options => {
                options.BusinessObject<ApplicationUser>();
                options.BusinessObject<Contact>();
            })
            // In XPO applications, uncomment the following line:
            // .AddXpoServices(); 
            // ...
        }
        // ...    
    }
}

Configure Authorization for Endpoints or Protect Business Object Data

You must define Security System permissions for business objects and properties you want to expose through a Web API Service (both built-in and custom endpoints). We do not recommend that you expose business object data to all users without security protection.

You can configure permissions using one of the following methods:

• In the code of the ModuleUpdater class (look for the Updater.cs file, because there may be different locations depending on your project configuration).
• In the administrative UI powered by XAF Blazor/WinForms (this feature requires the Universal license).

For more information, refer to the following concepts and examples:

• Create Predefined Users, Roles and Permissions in the Database
• How to restrict inter-departmental data access using Security Permissions (EF Core)

• Authenticate and Authorize Web API Endpoints

Expose or Hide Business Object Properties

Expose Properties

ASP.NET Core Web API/OData exposes public business class properties of simple/value types with a setter (writable) in a Web API response. Our Web API Service additionally exposes read-only calculated XPO properties of simple/value types without a setter (readonly) marked with PersistentAliasAttribute.

ASP.NET Core Web API/OData does not initially include complex type, reference, and collection business class properties in a Web API response. To include complex type, reference, and collection business class properties in a Web API response, use OData query options:

• Get a Reference Object
• Get an Associated Collection
• Change the Expansion Depth for Related Business Objects

Note

If you apply the AutoExpand attribute to a referenced property, you do not need to explicitly specify the $expand parameter in an OData query because it is automatically loaded and its data is included in the API response.

Hide Properties

To hide business class properties from the Web API Service’s responses, decorate them with the IgnoreDataMemberAttribute.

To specifically remove a property from the Web API Service’s OData interface, use the EntityTypeConfigurator.IgnoreProperty method. In this instance, the specified property may belong to the class itself or to its ancestor:

File: MySolution.WebApi\Startup.cs (MySolution.Blazor.Server\Startup.cs)

C#

services.AddXafWebApi(Configuration, options => { 
    options.BusinessObject<Contact>().ConfigureEntityType(b => {
        // Ignore this class's property.
        b.IgnoreProperty(o => o.Email);
        // Ignore a property of the parent `Person` class.
        b.IgnoreProperty(o => o.Company);
    }); 
}); 

The image below demonstrates the difference in the GET endpoint’s response when the above code is used:

For advanced OData entity model structure customization, refer to Change an EDM Model Structure using ODataModelBuilder.