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

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, and features many API design patterns as decorators (a.k.a. stereotypes) such as <<pagination>>. Its data contracts are inspired — but generalize from — message exchange formats such as JSON and the Jolie type system.

Hello World (Service API Edition)

The Hello World of MDSL and service design specifies a single endpoint HelloWorldEndpoint that exposes an operation sayHello:

API description HelloWorldAPI

data type SampleDTO {ID, D<string>}

endpoint type HelloWorldEndpoint
exposes 
  operation sayHello 
    expecting payload "in": D<string>  
    delivering payload SampleDTO

API provider HelloWorldAPIProvider
  offers HelloWorldEndpoint 
  at endpoint location "http://localhost:8000" 
  via protocol HTTP 
    binding resource HomeResource at "/"
      operation sayHello to POST 
  
API client HelloWorldAPIClient
  consumes HelloWorldEndpoint 
  from HelloWorldAPIProvider
  via protocol HTTP

sayHello accepts a single scalar string value D<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 as an identifier-data pair {ID, D}: the two elements in the pair are an identifier ID and some data (D). The names of these two “parameters” have not been specified yet (unlike "in", the data send in the request message of sayHello). The data element in the pair is a string; type of the ID parameter is yet unspecified. In addition to the endpoint type (a.k.a. service contract) HelloWorldEndpoint, an API client and an API provider working with this contract are defined (and bound to HTTP, a single home resource in this simple case).

Take a look at Hello World in Swagger/OpenAPI Specification in comparison. You can find such contract specification example here (note: this OpenAPI specification contains a few more details about the HTTP binding of the abstract contract).

Design Goals

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

Design Principles

To achieve the above design goals:

Tool Support

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

A Closer Look

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:2

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.

Language specification 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. Optional instance-level concepts:
    • API Provider with protocol bindings and, optionally, Service Level Agreements and evolution strategies such as Two in Production
    • API Client instances consuming the contracts exposed by providers
    • API Gateways (or intermediaries) acting both in client and in provider role; note that gateways are not featured in the simple example above
  4. Integration scenarios including stories
  5. Orchestration flows

See these concepts in action in the tutorial, the quick reference and on the example page.

Usage of and support for Microservice API Patterns (MAP)

MDSL supports all Microservice API Patterns one way or another:

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 such as API linters/contract validators, code/configuration generators, MDSL to OpenAPI or WSDL converters (work in progress).

More Information

MDSL Git Pages (this website)

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

  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 promising too!