Primer — Endpoint Types — API Provider and Client — Tutorial — Tools —Transformations
Overview
Microservice Domain-Specific Language (MDSL) abstracts from technology-specific interface description languages such as OpenAPI/Swagger, WSDL, and Protocol Buffers.
A First Example
An API with a single endpoint HelloWorldEndpoint
that exposes a single operation called sayHello
can be modelled as this:
API description HelloMDSLWorld
data type SampleDTO {ID, D<string>}
endpoint type HelloWorldEndpoint
exposes
operation sayHello
expecting payload "in": D<int>
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. This SampleDTO
is specified incompletely as an identifier-data pair {ID, D}
. Its two elements are an identifier ID
and some data D
. The names of these two “parameters” have not been specified yet. The data element D
is a string; the type of the ID
parameter is not unspecified. This is different from "in": D<int>
, the data send in the request message of sayHello
, which gives its single parameter a name, a role, and a type.
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).
An advanced example showing more contract feature appears in the MDSL Primer.
Quickstarts
- Extended overview: MDSL Primer
- Language Tutorial and Quick Reference
- Design Transformations and Refactorings
Language Specification Elements
- Service endpoint contract types follow this template:
endpoint type ... exposes operation ... expecting ... delivering ...
- Data contracts (schemas)
data type SampleDTO {ID, V}
in the above example
- 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
- Integration scenarios including user/job/test stories
- Orchestration flows.
Next Steps
MDSL Tools and Their Application
The following tools already support MDSL:
- An Eclipse plugin for MDSL, available from this update site, offers syntax checking highlighting, semantic validation, code completion, transformations, and generators.
- A Command-Line Interface (CLI) makes contract validation and generators available outside any IDE. Work in progress: MDSL Web Tools.
- Context Mapper can generate MDSL.
See MDSL Tools page for more information. Two blog posts, “Story-Driven Service Design: From Feature Story to Minimum Viable API Product” and “Event-Driven Service Design: Five Steps from Whiteboard to OpenAPI and Camel Flow” feature MDSL these tools in action.
MDSL Documentation (this website)
- Language reference:
- Service-oriented quick fixes and model transformations supporting “API First”
- IDL/code generators:
- Language and tools repository (GitHub): XText grammar, examples folder
External links
- Microservice API Patterns (MAP) and Interface Refactoring Catalog
- An end-to-end service design demo is available on Medium also featuring Context Mapper, a DSL for strategic DDD and rapid OOAD (Context Mapper can generate MDSL). The demo takes you from a user story to a walking microservice skeleton (Spring Boot, Hipster, Heroku) in seven steps (partially automated in model transformations).
- A microservices and DevOps conference report mentioning Context Mapper and MDSL.
- Lakeside Mutual repository, featuring Domain-Driven Design (DDD) and microservices in an insurance company scenario (JavaScript frontends and Spring Boot backends)
- Olaf Zimmermann’s Blog “The Concerned Architect”
Copyright: Olaf Zimmermann, 2018-2022. All rights reserved. See license information.