Home
Harmony Core is an open-source framework designed to help Synergy developers build RESTful web services that expose Synergy data and business logic using OData and ASP.NET Core with minimal effort.
We built our framework using best-of-breed industry standard tools, APIs, and environments, including:
- ASP.NET Core
- ASP.NET Core MVC
- ASP.NET Core OData
- ASP.NET Core Identity
- Entity Framework Core
- Swagger/OpenAPI
Harmony Core consists of libraries, CodeGen templates, and recommended coding practices and conventions. Here is an example Harmony Core service that includes a home page with sample example OData queries against the sample web service.
- Our source code is hosted on GitHub.
- Our binary releases are available on NuGet.
- Our development builds are available from a private NuGet repository.
We think REST is the best possible way to expose Synergy data and logic over a network. Our customers are most successful when they turn the logic and data they've worked on for the years into easily consumable black boxes of functionality. The best black boxes can be used without a proprietary protocol and without needing to make a complex series of calls that have little or no relation to one another. Maintaining state between calls is fraught with peril. It is difficult to protect a system sufficiently from misuse when a web service consumer is allowed to partially complete a transaction and then disappear. When possible, web service operations should be idempotent. If that isn't possible, they should at least strive to be atomic.
ASP.NET Core is a ground-up rewrite of the entire web stack for .NET. Microsoft has applied all the lessons learned over the years with large-scale deployment of ASP.NET. What they've come up with runs on both the full .NET Framework and .NET Core, and they've significantly improved the performance and general scalability characteristics. Unlike the original ASP.NET, everything is being developed in the open on GitHub with significant community engagement and contributions.
Entity Framework Core, commonly referenced as EF Core, is a full rewrite of Entity Framework. Much like other libraries Microsoft has been naming "Core", there has been a significant focus on portability, performance, and extensibility. The team has an explicit goal to provide support for non-relational databases (of which Synergy DBMS is one). This is a big change from the SQL-Server-centric Entity Framework 6.0 release that preceded EF Core. Because our Synergy Select class is capable of performing all the underlying read operations that EF Core supports, it is a great fit for accessing DataObjects. Write/update/delete operations are supported in our EF Core provider, but these use FileIO classes to enable custom I/O routines.
Open Data Protocol (OData) is an open protocol that allows the creation and consumption of queryable and interoperable RESTful APIs in a simple and standard way. When using OData for web services, we emit plain JSON data, which is easily consumable by nearly any client you can imagine. OData lets you expose the entities as operations your code supports, but it frees you from explicitly having to make every operation variant. Instead of writing code that exposes all customers, then writing other code that exposes all customer meeting certain criteria (like all customers in the state of California), with OData you simply expose the customers and let Entity Framework Core (an ASP.NET Core component) and OData handle the filtering. For example:
GET https://api.acme.com/customers?$filter=State eq 'CA'
But OData provides so much more than simple filtering. For example, if your Synergy repository includes information about the relationships between various data structures, then you can use OData to follow those relationships when querying the data. This is done using the OData $expand keyword, like this:
GET https://api.acme.com/customers(1234)?$expand=REL_Orders($select=OrderNumber,DateOrdered)
This example retrieves a single customer entity via a primary key read on the customer number, and the response will also include the order number abd order date for all orders placed by the customer. The actual data access is performed by our EF Core Provider, which translates OData queries into Synergy Select class operations.
There are many other built-in functions and predicates supported by OData, and you can learn more about them by following the OData basic tutorial. These functions dramatically reduce the amount of work you need to put into exposing Synergy logic and data via a web service.
You might be starting to wonder, what about security? Maybe you don't want to allow all of the built-in functions and predicates because certain users shouldn't have access to certain types of data. OData supports query validation, so you can implement a query validator to ensure that your extensive query functionality can only be used in the ways you deem appropriate.
And in addition to writing code, there are several other ways to interact with OData services. For example, there are numerous OData libraries designed to make accessing OData services easy in a variety of programming languages and development environments. And OData support is baked into some tools that are commonly used to access and manipulate data; examples include Microsoft Excel and Microsoft PowerBI Desktop.
Next topic: Required Tools