View on GitHub

Microservice DSL (MDSL)

A Domain-Specific Language (DSL) to specify (micro-)service contracts, their data representations and API endpoints.

HomeEndpoint TypesBindingsTutorialCheat SheetToolsTransformations

Primer: Getting Started with MDSL

MDSL supports the API Description pattern from Microservice API Patterns (MAP). It picks up MAP concepts such as API endpoint, operation, client and provider. Its data contracts are inspired — but generalize from — message exchange formats such as JSON and the Jolie type system.

Example (Service/API Edition)

The following example CustomerRelationshipManager extends concepts features in the MDSL “Hello World” with compensation, reporting, and state transitions:

API description SampleCRMScenario
version "1.0"
usage context PUBLIC_API for FRONTEND_INTEGRATION 
overview "Example in MDSL Primer"

data type Customer {"name": D<string>, 
                    "address": D<string>, 
                    "birthday": D<string>}
data type StatusCode "success": MD<bool> default is "true"

endpoint type CustomerRelationshipManager serves as PROCESSING_RESOURCE
exposes 
  operation createCustomer with responsibility STATE_CREATION_OPERATION
    expecting payload "customerRecord": Customer
    delivering payload "customerId": D<int>
    compensated by deleteCustomer
  operation upgradeCustomer with responsibility STATE_TRANSITION_OPERATION
    expecting payload "promotionCode": P // request partially specified
    delivering payload P // response unspecified
  operation deleteCustomer with responsibility STATE_DELETION_OPERATION
    expecting payload "customerId": D<int>
    delivering payload "success": StatusCode
    transitions from "customerIsActive" to "customerIsArchived"
  operation validateCustomerRecord with responsibility COMPUTATION_FUNCTION
    expecting payload "customerRecord": Customer
    delivering payload "isCompleteAndSound": D<bool>
    reporting error ValidationResultsReport 
      "issues": {"code":D<int>, "message":D<string>}+

createCustomer is marked with the pattern STATE_CREATION_OPERATION; the reverse operation is specified (compensated by deleteCustomer). upgradeCustomer also has a responsibility decorator, and its parameters are specified incompletely (P). deleteCustomer discloses the API-internal state transition that takes place (via the strings "customerIsActive" and "customerIsArchived"). Finally, validateCustomerRecord not only has a normal response payload, but also may return an error report.

Two data types Customer and StatusCode are made explicit, the others are inlined in the request and response message definitions. As a basic type, StatusCode has a default value defined.

The following blog posts feature MDSL and its tool usage step-by-step and provide additional examples:

Where and When to Use MDSL

Let us visualize the usage context of MDSL specifications with two hexagons, a notation and style that is quite popular in the microservices community:1

Solution Sketch of API Integration

If you want to leverage and promote microservices tenets such as polyglot programming and use multiple integration protocols, e.g., an HTTP resource API and message queuing, then MDSL is for you. The request and response message representations in the diagram can be specified with MDSL data contracts; the provided interface supports an MDSL endpoint type.

Design Goals

As a contract language for (micro-)service API design, MDSL should:

Design Principles

To achieve the above design goals:

Integration with Microservice API Patterns (MAP)

MDSL supports all Microservice API Patterns one way or another:

The pattern decorators/annotations and stereotypes are optional; if present, they make the API description more expressive and can be processed by tools such as API linters/contract validators, code/configuration generators, MDSL to OpenAPI or WSDL converters (work in progress).

Tool Support

At present, the following tools are available (see tools page for more information):

There is an MDSL generator in Context Mapper.

MDSL Documentation (this Website)

Publications

Copyright: Olaf Zimmermann, 2018-2022. All rights reserved. See license information.

  1. Octogons, as used to denote cells in Cell-Based Architectures (CBAs), look promising too! 

  2. The service and the data contract languages can be used independently of each other; for instance, data contracts for operations in contract types can also be specified in JSON Schema (but might not be supported by MDSL tools in that case).