Overview Domain Service Project
Introduction
Let's start with having a look on the project's structure and the UI elements used to represent the different components of a project.
After creating a new Domain Service Project you will be directed to the project's Overview page ( see setting up projects). On the left there is the main navigation bar offering the following categories:
The appearence of APIs, Domains and Integrations on the left side navigation is depending on if they are enabled or disabled as Extensions. By default they are enabled, but you can disable the extensions related to each one of them.
Overview page
The project's overview page is the starting point inside a project and provides the following information:
General information
Here you can find information about the project's "Acronym", "Git Provider", "Repository group", "Git repository path", "Stack", and "Stack version". Besides, it shows information the used "Event Support version" (1.0 or 2.0) for Domain Service Projects and furthermore, additional information on "Tags" and the "Icon", the project's "Description" and the name of the creator ("Created by") and the creation date ("Created on").
Depending on the implementation language there can be additional fields, e.g. the "Package Name", "Persitence Support" (MongoDB or RMDB) or "Saga Pattern Support" required for Domain Service Projects (Java).
Using the "Edit general information" action capability you´ll get the possibility to change "Name", "Tags", "Icon" and "Description" of the project.
Documentation
The documentation section on a project's overview page is intended to provide an overall documentation of the project and all of its components. It is pre-filled with a basic table of contents and a UML diagram showing the coarse structure of the project. See General capabilities of Solution Designer for further details on the Markdown editor and the diagram generator.
After creating a new project there will only be the headlines and some hints in the documentation section and the diagram will be empty as long as there are no elements modelled. The diagram will refresh automatically whenever you make changes to the design model.
Using the Documentation section is a perfect way to communicate ideas and concepts as well as to describe complex procedures or conditions. The built-in Markdown editor also offers support for creating native plantUML diagrams in case you want to visualize procedures that can't get auto-generated by Solution Designer.
Namespace Overview
This section gives an overview of all existing namespaces in a project and lets you easily create new namespaces. It is separated into the following categories:
- API Namespaces
- Domain Namespaces
- Integration Namespaces
Each category lists the existing namespaces in this category by adding a card for each namespace. By clicking on the header of this cards you will be directed to the namespace's instance page. Alternatively, you can use three-dots menu on each card to Edit or Delete a namespace. Each card also provides links to quickly access all its components.
Extensions
For the available Domain Service Projects a table with all the extensions of the project is shown. All type of Domain Service Projects have the following extensions enabled by default:
| Extension | Description |
|---|---|
| Aggregate Persistence Support | Model and implement your entities and simply store them in a database. For Java Spring Boot "MongoDB" or "RMDB" are available. For TypeScript only "MongoDB" is currently supported. |
| Business Event Support | Send business events via Kafka and react on them with EventAgents. The version can be changed in the General Information |
| Distributed Tracing Support | Support for tracing user requests end-to-end across microservices. |
| JWT Checking | Validate all incoming requests for a valid JSON Web Token (JWT), requires OIDC Connection. |
| OIDC Connection | Provides settings for connections to an OIDC compliant identity server. |
| OpenAPI Documentation Publishing | Publishes the OpenAPI Documentation of the APIs of the project. |
Project type related extensions
In addition to the extensions mentioned above following extensions are enabled by default, depending on the type of the project:
| Extension | Description | Availability |
|---|---|---|
| Aggregate Mutation Support | Automatically sends events when an aggregate was changed within the database. | TypeScript |
| Audit Logging Emitter | Emit Audit Logs to a central listener. Requires the Audit Listener to be available in the application. | TypeScript |
| Health Checks | Provides basic health checks. | TypeScript |
| API modelling | Model and implement a secure REST API and publish it as an OpenAPI specification. | JAVA Spring Boot 2.0 |
| Domain modelling | Model and implement your business logic based on Domain Driven Design principles. | JAVA Spring Boot 2.0 |
| Integration modelling | Model and implement integrations to other services. | JAVA Spring Boot 2.0 |
| Saga Pattern Support | Modeling and code-generation support to handle distributed transactions | JAVA Spring Boot 2.0 |
| Unit Test Support | Write unit tests directly in your code and execute them before the project gets deployed. | JAVA Spring Boot |
The Edit extension capability is available to modify extensions of your project. Extensions can be enabled or disabled and additional configuration values can be set if needed.
Extensions can't be enabled or disabled for Domain Service projects with Stack 1.0.
Introduction to Namespaces
A Domain Service Projects in IBM Industry Solutions Workbench is always separated into three layers:
- APIs: This layer is used to provide one or more API(s) based on the OpenAPI standard that will get consumed by other projects or external systems
- Domains: This layer holds the business logic of the microservice
- Integrations: This layer is responsible for consuming REST APIs provided by other projects or external systems
Separating the project into these layers aims to protect the business logic through putting an anti-corruption layer around. It abstracts away the business logic from the API specification, so you can update or evolve the inner logic without changing the outer implementation. Same applies for the integration layer, where you could update or evolve how to process the queried data while still having the same implementation to communicate with the external service.
Depending on the purpose and intention of the project you are planning, you may not need to create all types of namespaces. In case you only want to provide an API that processes the user's input (request) and returns the result (response), you would not need to create an integration namespace.
API Namespaces
As already mentioned, API Namespaces in Solution Designer are used to build REST APIs that can be consumed by other projects or external systems. Each modelled API Namespace results in a separate REST API based on the OpenAPI standard with its own API specification. That means, you can design the microservice to have as many separate APIs as needed or just model one single API depending on the requirements.
There are two different approaches when modelling an API Namespace:
- create the API from scratch
- create the model of the API Namespace based on an existing API specification
While the first approach fits best when you are not yet fully decided on how the API will look like exactly in the end, the second approach is intended for API First strategies. Solution Designer offers you to upload an API specification either in OpenAPI 3.0 (.yaml) or Swagger 2.0 (.json) format and auto-generates the whole API namespace with a single click. This includes all Paths, Operations, Parameters, Schemas and Responses that form the specified API.
See API Namespaces for further details on creating and working with API Namespaces.
Domain Namespaces
Domain Namespaces are used to put all the business logic away from communication logic. That ensures, that you don't have to touch the implementation code of the API operations if you intend to change the way how you process the input data. Any data exchange between an API Namespace and a Domain namespace will be handled by mapping properties between them. Same applies when exchanging data with an integration namespace. You always have the business logic kept separate from communicating with external systems.
As the design model of Domain Service Projects is based on Domain Driven Design principles, Domain Namespaces are the place to model the following elements:
- Root entities/aggregate roots
- Entities
- Services
- Commands
- Events
See Domain Namespaces for further details on creating and working with Domain Namespaces.
Depending on your project's requirements you can create and model as many Domain Namespaces as needed.
Integration Namespaces
The last of the three layers is the Integration Namespace which is used to model services, entities and their properties necessary to consume external REST APIs. Solution Designer offers to create API dependencies that support the user to integrate an external API. You have the chance to upload an existing API specification either in OpenAPI 3.0 (.yaml) or Swagger 2.0 (.json) format and Solution Designer will then create all necessary methods for implementing each of the HTTP operations stated in the API specification. This way, you don't have to prepare each API call on your own and instead can focus on implementing the business logic.
Furthermore, there is the concept of API bindings which can be specified for each API dependency. They allow specifying additional information regarding the consumption of an API, e.g. authorization token, URLs, API keys, or just any additional value needed to communicate with the external API.
You can specify values in API bindings and overwrite them for different deployment targets. This allows you to adjust certain values depending on the target environment without having to change your implementation code.
See Integration Namespaces for further details on creating and working with integration namespaces.
Depending on your project's requirements you can create and model as many Integration Namespaces as needed.