Beef

<br/>

<br/>

Introduction

Beef framework has been primarily created to support the industralisation of API development.

A means to have software developers focus directly on the accelerated delivery of business value; with consistently higher quality outcomes at an overall lower cost.

The key industralisation goals are:

1. Value – focus on business value, not on boilerplate
2. Acceleration – improve velocity; reduce costs and time to market
3. Simplicity – increase effective usage and minimize learning
4. Standardized – increase knowledgeable resource pool
5. Consistency – improve overall quality and maintainability
6. Flexibility – enable innovation and evolution easily over time
7. Confidence – reduced delivery timeframes and risk

<br/>

Demonstration

The following video (includes sound) provides a high-level demonstration of Beef and its capabilities.

https://github.com/Avanade/Beef/assets/12836934/693d4839-dfde-4360-9994-33f8dc10e3a1

<br/>

Version 5

NOTE: A new major version of Beef, verison 5, was released on 26-Jan-2023. The samples have been updated accordingly, as has the related documentation. As such, development on the previous version (v4.x) will for the most part halt; only significant issues will now be addressed (for a period of time). The new version is a major refactoring (improvement and simplification) with respect to the underlying runtime primarily, and although effort was made to minimize impacts on upgrading from v4, this was unfortunately unavoidable. Guidance is provided to assist with upgrading from v4.2.x to v5.x where applicable.

<br/>

Composition

Beef is ostensibly the code-generation engine, and solution orchestration, that ultimately takes dependencies on the following capabilities to enable the end-to-functionality and testing thereof in a standardized (albiet somewhat opinionated) manner:

• CoreEx - provides the core runtime capabilties (extends .NET core);
• UnitTestEx - provides extended unit and intra-domain integration testing;
• DbEx - provides extended database management capabilties;
• OnRamp - provides the underlying code-generation engine functionality.

Prior to version 5.x, Beef was all encompassing. These capabilities have been extracted, simplified and refactored to be first class frameworks in their own right, and made into the repos listed above. This allows them to be used and maintained independently to Beef; therefore, offering greater opportunities for reuse versus all-or-nothing.

<br/>

Rapid enterprise-grade API development

As a result of the Beef Architecture, supporting Framework and included Code Generation capabilities, enterprise-grade APIs can be developed in a matter of hours, not days, in a standardized and consistent manner.

The APIs created will have the following capabilities out-of-the-box with limited developer effort, so the developer can focus on the key business value:

• Rich Entity (DTO) functionality including INotifyPropertyChanged, IEditableObject, IEquatable, ICopyFrom, ICleanUp, IPrimaryKey, etc.
• Rich Reference data capabilities, including caching, optimized serialisation, and enriched API endpoints.
• Rich Validation capability to simplify and ensure data integrity and consistency.
• CRUD (Create, Read, Update and Delete) for Database (Stored procedures and Entity Framework), Cosmos DB and HttpAgent in a standardized manner.
• Paging (skip and top) and resulting total count, that flows from API through to the underlying data source in a consistent and seamless manner.
• ETag (concurrency) and If-Match/If-None-Match handling.
• JSON response field filtering (include/exclude) to minimize resulting payload size (e.g. $fields=firstname,lastname)
• HTTP Patch support, where required, in a simplified and consistent manner.
• An end-to-end intra-domain integration testing approach enables effective tests to be built easily and quickly.
• Event publishing (and subscribing) to enable an event-driven architecture.
• Runtime capabilities can be added, where applicable, using the out-of-the-box .NET framework Dependency Injection (DI) capabilites.
• An approach and tooling to automate and manage database using DbEx set up, configuration, and deployment.

To implement these included capabilities would literally take months/years to build and test; these are available for developers to use immediately, and contribute back if so inclined. The capabilities and implementations have been influenced by Microsoft's best practices for cloud applications; specifically:

• RESTful web API design
• Web API implementation

To get started a .NET Core template capability is provided to enable you to get a solution up and running in minutes.

<br/>

Architecture

Beef has been developed to encourage the standardisation and industrialisation of the tiering and layering within the microservices (APIs) of an Application Architecture.

<br/>

API-enabled domain-based channel-agnostic architecture

The conceptual architecture is as follows; with Beef being targeted specifically at implementation of the API tier.

The key concepts are as follows:

• Channel-agnostic - the APIs are based around the key entities and the operations that can be performed on them:

  • APIs represent the key trust boundary; as such, they make no assumptions on the consumer. The APIs will always validate the request data, and house the application’s functional business and orchestration rules.
  • APIs should not be developed to service a specific user interface interaction; as the APIs are agnostic to the consumer. The consumer has the responsibility of coordinating across API calls.

• Domain-based – the APIs are based around, and encapsulate, the capabilities for a functional domain:

  • Outcome of a Domain-Driven Design; divides capapabilities into different Bounded Contexts.
  • Encourages micro vs monolithic services.

<br/>

Microservices

An architectural pattern for creating domain-based APIs:

• Is a software architecture style in which complex applications are composed of small, independent processes communicating with each other using language-agnostic APIs.
• These services are small, highly decoupled and focus on doing a small task, facilitating a modular approach to system-building.
• Implementation independence:
  • Loose coupling – should have its own persistence repository; data is duplicated (synchronized), not shared; eventual consistency; no distributed transactions.
  • Polyglot persistence / programming – use the best persistence repository to support the storage requirements; use a mix of programming languages (fit-for-purpose). Note: Beef provides a C# / .NET implementation approach as one option.
  • Eventual consistency - for the most part, eventual consistency is good enough; real-time distributed transactional integrity is rarely required (although generally desired). An asynchronous messaging system, such as Queues or a Service Bus, can be leveraged to orchestrate cross domain data (eventual) consistency.

“Micro” doesn’t imply number of lines of code; but a bounded concept / business capability within your Domain. - http://herdingcode.com

<br/>

Tiering and layering

The architecture supports a domain-based channel-agnostic microservices approach. The API service endpoints represent a light-weight facade for the Business (domain logic) tier, that is ultimately responsible for the fulfillment of the request.

The following represents the prescribed tiering and layering of the architecture:

Given this architecture, the .NET Solution you create using Beef should adhere to the prescribed [solution structur