Skip to main content

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.

💡tip

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.

ℹ️note

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.

💡tip

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.

ℹ️note

Depending on your project's requirements you can create and model as many Integration Namespaces as needed.

Course Create a REST API