OnionAPI Template Overview

According to Fuji Nguyen, the author of the OnionAPI template, "The OnionAPI template is a blueprint for developing sophisticated REST APIs. It can save developers at least 40 hours compared to starting a REST API project from the ground up."

What is a Visual Studio Template?

A Visual Studio template supplies the essential files for a specific project type, including standard assembly references, default project properties, and compiler settings. Visual Studio comes pre-installed with numerous project templates, such as the ASP.NET Web Application and Class Library templates, which you can select when initiating a new project.

What is the OnionAPI Template?

The OnionAPI template enables developers to scaffold an ASP.NET Core REST API project following a clean architecture approach (illustrated in Figure 1).

After specifying the project name, the template generates five projects within the Visual Studio solution, each prefixed with the project name and organized with appropriate namespaces in the source code. The five projects include:

1. Domain — containing entities and common models
2. Application — encompassing interfaces, CQRS features, exceptions, and behaviors
3. Infrastructure.Persistence — data access API leveraging Entity Framework
4. Infrastructure.Shared — housing common services like Mail Service and DateTime Service
5. WebApi — for API controllers to expose REST API resources and endpoints

Figure 2 showcases the source code organization scaffolded by the OnionAPI template for the sample project MyOnionApi. It illustrates the grouping of five projects into three folders: Core, Infrastructure, and Presentation, aligned with the layers outlined in the Clean Architecture pattern.

The solution's technology stack promotes a loosely-coupled and inverted-dependency architecture, employing sound design patterns and practices:

1. ASP.NET CORE 6 — a framework for building RESTful services, often referred to as web APIs, using C#
2. Repository Pattern — serves as an abstraction layer between the data access layer and the controller
3. CQRS (Command and Query Responsibility Segregation) Pattern — separates read and write operations for a data store to enhance performance, scalability, and security
4. Entity Framework Core — a lightweight, extensible, open-source, cross-platform variant of the widely-used Entity Framework data access technology
5. Swashbuckle — easily integrates Swagger into WebApi projects, blending ApiExplorer and Swagger/swagger-ui for a rich API discovery and documentation experience
6. Bogus — a .NET library providing realistic mock data for rapid REST API design and testing

Part 1 — Download and Install OnionAPI Template

You can acquire the OnionAPI template from the Visual Studio Marketplace, as depicted in Figure 3. As of this writing, the template has been downloaded 975 times by developers.

After downloading, click on the VSIXTemplateOnionAPI.vsix file to install the extension. For those unfamiliar with Visual Studio Extensions, refer to the Manage Extensions for Visual Studio for installation guidance.

Part 2 — Scaffold a New REST API Project with OnionAPI Template

The simplest method to create a new project is by starting from a template tailored for a specific application type. A project template includes a foundational set of pre-generated code files, configuration files, assets, and settings.

Upon opening Visual Studio, the start window appears, where you can opt to create a new project, as shown in Figure 4.

If Visual Studio is already open, you can create a new project by selecting File > New > Project from the menu bar, as illustrated in Figure 5, or by clicking the New Project button on the toolbar.

Task 1 — Select a Template Type

On the "Create a new project" page, a list of your recently used templates will be displayed on the left, arranged by most recently used.

If you are not selecting from the recent templates, you can filter all available project templates by entering search terms in the search box, such as "OnionAPI."

Task 2 — Create a Solution

On the "Create a new project" screen, search for and select the OnionAPI template, then click the Next button. Visual aid can be found in Figure 6.

Enter the project name (e.g., MyOnionAPI) and click the Create button, as shown in Figure 7.

Press F5 to run the project. Swagger should display in the browser, as illustrated in Figure 8.

Part 3 — Exploring Filtering, Sorting, Paging, and Shaping Features

The OnionAPI template generates two REST resources:

1. Employees — A mock REST API resource where data is dynamically created using the Bogus library at runtime. For more information about Bogus, refer to the Related Stories section later in this guide.
2. Positions — This REST API resource retrieves its data from the actual database table, Positions. When the project runs for the first time, this table is automatically populated with 1,000 rows of dummy data.

To test the REST API in Swagger (refer to Figure 9 for visual guidance):

1. Click on Employees > GET to expand the view.
2. Click on Try it out.
3. Enter parameters (leave blank for defaults).
4. Click on the Execute button.
5. Review the JSON output.

Figure 10 illustrates a sample screenshot of the JSON output. For performance, server-side paging is utilized. The response body contains a "wrapper" with user-friendly data for frontend applications.

1. pageNumber — pagination index (e.g., 1, 2, 3). Default is page 1.
2. pageSize — number of records per page. Default is 10.
3. recordsFiltered — count of records matching the search criteria. For this example, the criteria is "Chief."
4. recordsTotal — total number of employee records in the database.
5. succeeded — boolean indicating the status of the web API response.
6. message — user-friendly error message, if applicable.
7. errors — system error, if any.
8. data — JSON response data.

The data response comprises eleven columns. If you want to reduce the response to fewer columns to lessen the data sent over the network, you can specify the required columns. For instance, if the frontend app only needs firstName, lastName, and employeeTitle, input these column names in the Fields parameter as shown in Figure 11, and the JSON response will include only those three columns in the "Data" section, as shown in Figure 12. Additional tutorials on Pagination can be found in the References section.

The scaffolded source code also includes example methods for data modification within the Positions resource. As illustrated in Figure 13, methods such as POST, GET, PUT, and DELETE are available to facilitate CRUD operations.