TL;DR

Microservice Domain-Specific Language (MDSL) abstracts from platform-specific interface description languages such as Swagger, WSDL, and Protocol Buffers. Grammar, editor, examples and a quick reference are available; a getting started tutorial as well as validation and generation tools are under construction.

Quick Start

A First Example

The Hello World of MDSL models an API with a single endpoint HelloWorldEndpoint that exposes a single operation called sayHello:

API description HelloWorldAPI

data type SampleDTO {ID, V} 

endpoint type HelloWorldEndpoint
exposes 
  operation sayHello 
    expecting payload V<string>  
    delivering payload SampleDTO

API provider HelloWorldAPIProvider1
  offers HelloWorldEndpoint

API client HelloWorldAPIClient1
  consumes HelloWorldEndpoint

sayHello accepts a single scalar string value V<string> as input. This operation returns a Data Transfer Object (DTO) called SampleDTO as output, which is modeled explicitly so that its specification can be reused. SampleDTO is specified incompletely: an identifier-value pair has to be present, but the “parameter” names and the type of the value V have not been specified yet; string could be assumed to be the default, but this is not expressed above.

Take a look at Hello World in Swagger/Open API Specification in comparison. You can find such contract specification here.

Design Goals

A contract language for (micro-)service API design should/must:

• Support agile modeling, for instance in API design workshops:
  • Readability over parsing efficiency (in language design)
  • Partial specifications as first-class language concepts (to be refined iteratively)
• Promote platform independence:
  • Microservice API Patterns (MAP) as first-class language elements annotating/decorating endpoint types, operations, and representation elements
  • Not bound to HTTP (unlike Swagger and its successor Open API Specification, OAS) or other protocols and message exchange formats
• Support meet-in-the-middle service design:
  • Top-down from requirements (for instance, integration stories)
  • Bottom up from existing systems (represented, for instance, as DDD-style context maps)

Design Principles

To achieve the above design goals, we decided that:

• The abstract syntax of MDSL is inspired and driven by the domain model and concepts of Microservice API Patterns (MAP), for instance featuring endpoints, operations, and data representation elements.
• The concrete syntax of service endpoint contracts is elaborate; the concrete syntax of data contracts is compact yet simple and abstracts from data exchange formats such as XML and JSON, as well as service-centric programming languages such as Ballerina and Jolie.¹

A Closer Look

Where and when to use MDSL

Let us visualize the usage context of MDSL specifications with two hexagons, as suggested by the microservices community:²

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.

Language elements

1. Service endpoint contract types follow this template: endpoint type ... exposes operation ... expecting ... delivering ...
2. Data contracts (schemas): data type SampleDTO {ID, V} in the above example
3. Other concepts:
   • API Provider with Service Level Agreements and evolution strategies such as Two in Production
   • API Client instances
   • API Gateways (a.k.a. intermediaries), not featured in the above example

See these concepts in action in the quick reference and on the examples page.

Usage of and support for Microservice API Patterns (MAP)

MDSL supports all Microservice API Patterns one way or another:

• The basic representation elements serve as MDSL grammar rules in the data contract part, e.g., ParameterTree and AtomicParameter
• Foundation patterns may appear as decorators/annotations for the entire API description, e.g., PUBLIC_API, FRONTEND_INTEGRATION (not shown in the Hello World example).
• Some responsibility patterns serve as decorators/annotations for endpoint roles and responsibilities, e.g., PROCESSING_RESOURCE and MASTER_DATA_HOLDER (enum/label).
• Other responsibility patterns are represented as decorators/annotations for operation responsibilities, e.g., COMPUTATION_FUNCTION and EVENT_PROCESSOR.
• Finally, the advanced structural representation patterns and most quality patterns appear as stereotypes annotating representation elements, e.g., <<Pagination>>, <<Embedded_Entity>>, <<Wish_List>>.

The four types of decorators/annotations and stereotypes are optional; if present, they make the API description more expressive and can be processed by tools (e.g., linters/validators, code/configuration generators, MDSL to Swagger/WSDL converters).

Tutorial

Ready to start/learn more? Click here.

More Information

MDSL Git Pages (this website)

• Service endpoint contract types
• Data contracts (schemas)
• Quick reference
• Examples
• Optional/experimental language elements on the instance leve (provider, client, gateway)

Direct links into repository (that still is private; contact owner for access)

• Full grammar
• More examples

External links

• Public MAP website, access to team-internal preview website available upon request (features more patterns than the public one, in intermediate draft form)
• Lakeside Mutual repository, features Domain-Driven Design (DDD) and microservices in an insurance company scenario (JavaScript frontends and Spring Boot backends)
• Context Mapper, a DSL for strategic DDD

Copyright: Olaf Zimmermann, 2019. All rights reserved.

1. 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). ↩

2. Octogons, as used to denote cells in Cell-Based Architectures (CBAs), look cool too ;-) ↩