ActiveQL
From the definition of your business domain as graph to full fledged GraphQL API application and Admin UI in minutes - with convention over configuration over code (3CO).
API 1st and Domain Driven Design
We believe in Domain Driven Design. That is understanding a system in terms of business entites and its relationships to each other.
We believe in API 1st when developing software that is connected to other systems. That is exposing your software features as an API.
Combining these two means to expose your business domain model through an API. Any other part (from different user interfaces, integration with other systems to infrastructure task etc.) uses this API as a common understanding of your business domain.
We think GraphQL (opens in a new tab) is a great way to expose your business domain in such a way. Implementing a GraphQL API can be a cumbersome task though. You need to decide how to structure your schema, how to handle concepts like permissions, searching, sorting, paging, how to implement resolvers that read data from and write data to a database or similar, validate input, relationships etc. And implement it with quite some repetitive code.
ActiveQL supports this development with a highly opinionated generation of a GraphQL schema and resolvers. You can run a GraphQL API directly from the description of a business domain (mainly entities and its relations to each other). This gives you the the freedom to concentrate on the implementation of any non-default functionality on top of that. It does not restrict you in any way how implement your API, what libraries you prefer etc.
Although ActiveQL is based on GraphQL principles it allows you to offer an API via REST too. It generates a swagger / OpenAPI schema description and serves the REST endpoints for any scenario in which a client prefers to use REST. For more see graphql-andor-rest
Terminologies
We use the this terms in the following meaning throughout this documentation.
| Term | Description |
|---|---|
| Business Domain | Description of your real world business domain in terms of entities with attributes, operations and relationships. Think of UML class diagrams - or even better as graph with nodes and edges. |
| DomainConfiguration | Any configuration in JSON, typescript or YAML to describe or configure (a part) of your business domain. A Domain Configuration can consist of Entity Configurations, Enum Configurations, Operation Configurations, Decision Tables, Type Definitions, Custom Queries and Custom Mutations. |
| DomainGraph | This is actually what an ActiveQL runtime would execute. It consits of all DomainConfigurations merged and resolved into a single object. |
| Entity | Any thing in your business domain. Think of a UML class or SQL table. |
| Entity Item | Any instance of an entity, think of a graph-node, class instance or table row. |
| Association | Any relation between types or entities think of a graph-edge, UML association or foreign key in SQL. |
| Operation | While ActiveQL will generate basic (you might call them anemic) mutations to create, update, delete entities, you can implement business specific operations that will generate mutations accordingly. |
| Custom Queries & Mutations | ActiveQL generates per convention a number of queries and mutations around your entity definitions. You can however add your own types, queries and mutations to the GraphQL schema - these are called Custom Queries & Mutations |
| Expression | a FEEL (opens in a new tab) term that has access to the runtime and the query/mutation context/data and can be evaluated to a result |
| Decision Table | A way to express semi-complex business logic, mainly validation in a configurative style (using Expressions) following the DMN (opens in a new tab) standard. |
| Callback | Any logic that you implement using Typescript/Javascript to describe a complex aspect of your business graph. |
GraphQL and/or REST
Besides GraphQL REST is a popular approach for building APIs. Each technology has its own strengths and weaknesses. REST is a well-established approach that has been used for many years, and it is widely supported by clients and servers. REST APIs typically use HTTP verbs (GET, POST, PUT, DELETE) to represent different operations, and they often return data in JSON format. In contrast, GraphQL is a newer approach that offers a more flexible and efficient way of fetching data from a server. Instead of defining multiple endpoints for different types of data, GraphQL provides a single endpoint that clients can use to request exactly the data they need. This reduces the amount of data transferred over the network and can improve the performance of the application.
While ActiveQL aims at GraphQL as API technology, you don't have decide against REST. Your API is available over REST as well, allowing clients to choose the approach that best fits their needs. This is achieved by using SOFA [https://the-guild.dev/graphql/sofa-api (opens in a new tab)]. You can disable / enable the REST endpoint in the runtime configuration.
Throughout the documentation we will only mention GraphQL but keep in mind, that any Query and Mutation can also be called by it's corresponding REST service.