Home — Endpoint Types — Bindings — Tutorial — Cheat Sheet — Tools — Transformations

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:

• “Story-Driven Service Design: From Feature Story to Minimum Viable API Product”
• “Event-Driven Service Design: Five Steps from Whiteboard to OpenAPI and Camel Flow”
• “Domain-Driven Service Design with Context Mapper and MDSL”

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

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:

• Facilitate agile modeling practices, for instance in API design workshops:
  • Value and promote readability over parsing efficiency (in language design)
  • Support partial specifications as first-class language concepts to be refined iteratively (see above example {ID, D})
• Promote platform independence:
  • Feature Microservice API Patterns (MAP) as first-class language elements annotating/decorating endpoint types, operations, and representation elements
  • Not be limited to HTTP (unlike Swagger and its successor OpenAPI Specification) or any other single protocol or message exchange format
• Support meet-in-the-middle service design:
  • Top-down from requirements (for instance, user stories for integration scenarios), as for instance proposed as an activity in the Design Practice Repository (DPR)
  • Bottom up from existing systems (represented, for instance, as DDD-style context maps)

Design Principles

To achieve the above design goals:

• The abstract syntax of MDSL is inspired and driven by the domain model and concepts of Microservice API Patterns (MAP), 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; it abstracts from data exchange formats such as XML and JSON, as well as service-centric programming languages such as Ballerina and Jolie.²
• MDSL features many API design patterns as decorators (also known as annotations or stereotypes) such as PROCESSING_RESOURCE, RETRIEVAL_OPERATION, and <<Pagination>> (see below).

Integration with 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, for instance, ParameterTree and AtomicParameter.
• Foundation patterns may appear as decorators/annotations for the entire API description, for instance, PUBLIC_API, FRONTEND_INTEGRATION (not shown in the above HelloWorldAPI example).
• Some responsibility patterns serve as decorators/annotations for endpoint roles and responsibilities, for example PROCESSING_RESOURCE and MASTER_DATA_HOLDER (enum/label).
• Other responsibility patterns are represented as decorator annotations for operation responsibilities, for instance, COMPUTATION_FUNCTION and EVENT_PROCESSOR.
• Finally, the advanced structural representation patterns and many quality patterns appear as stereotypes annotating representation elements. Two examples are <<Embedded_Entity>> and <<Wish_List>>.

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

• An Eclipse-based Editor and API Linter, also offering transformations for rapid, goal-driven API design (“API first”)
• Command-Line Interface (CLI) tools to validate a specification, to generate platform-specific contracts (OpenAPI, gRPC, Jolie) and reports
• Work in progress: MDSL Web Tools.

There is an MDSL generator in Context Mapper.

MDSL Documentation (this Website)

• API usage scenarios and stories
• Orchestration flows
• Service endpoint contract types
• Data contracts (schemas)
• General binding information and HTTP-/REST-specific binding details
• Optional language elements on the instance level (provider, client, gateway)
• Tutorial and example
• Quick reference
• Transformations and refactorings (in tools)

Publications

• Section 5.2 in From OpenAPI Fragments to API Pattern Primitives and Design Smells, Proc. of European Conference on Pattern Languages of Programs (EuroPLoP) 2021 by Souhaila Serbout, Cesare Pautasso, Uwe Zdun, and Olaf Zimmermann features MDSL (PDF)
• Zimmermann, Olaf: Dimensions of Successful Web API Design and Evolution: Context, Contracts, Components, Keynote, 20th International Conference on Web Engineering (ICWE), June 11, 2020. (PDF, blog post)
• Kapferer, Stefan and Zimmermann, Olaf: Domain-driven Service Design — Context Modeling, Model Refactoring and Contract Generation. Proc. of SummerSoC 2020 conference, Springer CCIS Volume 1310 (PDF, Presentation)
• Stocker, Mirko and Zimmermann, Olaf: “DPR: an Open Source Repository Collecting Mighty Methods”, public GitHub repository and LeanPub e-book

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