Design Goals

As a contract language for service and API design, MDSL aims at facilitating agile modeling practices, API sketching, and API design workshops. It is supposed to be readable for all stakeholder groups involved in API design and evolution. MDSL should support partial specifications that can be refined iteratively. To be usable in tutorials and publications such as this book, its syntax must be compact so that a nontrivial API contract still fits on one book page or presentation slide (or less).

MDSL can be used in top-down API design from requirements (for instance, user stories for integration scenarios and API sketches) down to code and deployment artifacts and in bottom-up discovery of internal interfaces in existing systems, possibly wrapped in public, community, or solution-internal remote APIs. One example of a top-down design process is Align-Define-Design-Refine (ADDR) [Higginbotham 2021], as introduced at the beginning of Part 2; a discovery tool with MDSL support is the domain-driven Context Mapper [Kapferer 2021].

MDSL aims at platform independence of API designs. API DESCRIPTIONS created with MDSL are not limited to HTTP or any other single protocol or message exchange format. The HTTP protocol design deviates from most interface definition languages and RPC-style communication protocols in many ways. Hence, MDSL has to provide configurable provider-to-technology bindings that surmount protocol differences—without losing either generality or specificity.

“Hello World” (API Edition)

The “Hello World” of MDSL and service API design look as follows:

Click here to view code image

API description HelloWorldAPI

data type SampleDTO {ID<int>, "someData": 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

There is a single endpoint type, HelloWorldEndpoint, that exposes an operation sayHello. This operation has a single inlined request parameter, "in": D<string>, and returns an unnamed data transfer object (DTO) called SampleDTO as output. This DTO is modeled explicitly so that its specification can be reused. The sample DTO is a PARAMETER TREE, {ID<int>, "someData": D<string>}, which is flat in this case. The DATA ELEMENT D in the tree is called "someData" and has a string type; the unnamed ID parameter, an ID ELEMENT, is of type integer.

Each endpoint type describes a platform-independent API contract, possibly provided multiple times. In addition to the endpoint type HelloWorldEndpoint, the example contains an API provider instance HelloWorldAPIProvider exposing an API implementation that binds the abstract endpoint type to HTTP. The endpoint type is bound to a single HTTP resource HomeResource in the example. The single endpoint operation sayHello is bound to the POST method in this single resource. The resource URI is assembled from two parts marked with the keyword at, one on the endpoint level and one on the resource level. The request parameters could be bound individually and explicitly to QUERY or PATH or other parameter types defined in the HTTP RFCs; this is not shown in the example, and a default binding to the request BODY is assumed.

It is possible to specify data types preliminarily:

Click here to view code image

data type SampleDTOStub {ID, "justAName"}

SampleDTOStub is specified incompletely. The first element in this flat PARAMETER TREE has an identifier role ID, but it does not have a name yet and its type is unknown still. The role and type of the second parameter have not been specified either; it merely consists of "justAName". Such incomplete, preliminary specifications are useful when only sketching interfaces at early design stages or when the details in a given modeling context are not of concern.

The online “Primer: Getting Started with MDSL”² and the project repository provide additional examples.

2. https://microservice-api-patterns.github.io/MDSL-Specification/primer.

API Endpoint Types (with Message Specifications)

The grammar of MDSL is inspired by the domain model from Chapter 1. An API DESCRIPTION in MDSL features one or more endpoint types, which expose operations. These operations expect and deliver request and/or response messages. The request and response messages sent and received by operations consist of simple or structured data. A comprehensive example looks as follows:

Click here to view code image

API description CustomerRelationshipManagementExample

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

The CustomerRelationshipManager API exposes and serves as a PROCESSING_RESOURCE (or, following our layout convention for pattern names, as a PROCESSING RESOURCE). This is one of the responsibility patterns in Chapter 5. Its four operations differ in their read-write characteristics; this is expressed by the with responsibility decorators. For instance, upgradeCustomer is a STATE_TRANSITION_OPERATION. All operations in this example have request and response messages (which is not mandatory in MDSL, as message exchange patterns may vary). The header and payload content of request and response messages is modeled via MDSL data transfer representations, introduced in the section “Data Types and Data Contracts” that follows.

Some of the operations define undo operations (compensated by) and state transitions (transitions from ... to). The operation validateCustomer-Record can return an ERROR REPORT, which is a pattern from Chapter 6. Note that one or more issues can be reported in ValidationResultsReport due to its “at least one” cardinality, indicted with the plus symbol, "+". This operation also features a request header, "complianceLevel": MD<int>, which has a metadata role and an integer type.

See “Service Endpoint Contracts in MDSL” in the online language specification for more explanations [Zimmermann 2022].

Data Types and Data Contracts

Throughout the book, we emphasized the importance of data modeling; the Published Language of an API contains data representations in several places, which may be flat or nested:

• Endpoint types define operations, which have request and (optionally) response messages containing payload content and metadata headers. The structure of these messages has to be specified unambiguously and agreed upon to achieve interoperability as well as accuracy, and it must ensure a positive client developer experience.

• When certain data structures are used by multiple operations, these operations may refer to shared data transfer representations (which are message-level pendants to DTOs internal to programs). Such representations become part of one or more API endpoint contracts.

• APIs may be used to emit and receive events. Such events also require data definitions.

API data definitions have a strong impact on the success of an API because the amount of coupling between client and provider is influenced by these definitions. MDSL supports data modeling in several ways, addressing the preceding usage scenarios. The MDSL data types are inspired—and generalize from—message exchange formats such as JSON. Here are two examples:

Click here to view code image

data type SampleDTO {ID, D<string>}

data type Customer {
  "name": D<string>,
  "address": {"street": D<string>, "city": D<string>}*,
  "birthday": D<string> }

The basic structure patterns from Chapter 4, ATOMIC PARAMETER and PARAMETER TREE in particular, provide the type system of MDSL. In the example, "name": D<string> is an ATOMIC PARAMETER, and Customer is a nested PARAMETER TREE, containing an inner PARAMETER TREE representing one or more "address" ele-ments. This is indicated by the asterisk * at the end of its definition.

"address": {"street": D<string>, "city": D<string>}

data type CustomerProductForest [
  "customers": { "customer": CustomerWithAddressAndMoveHistory}*;
  "products": { "product": ID<string> }
]

operation createCustomer
  expecting payload "customer": D
  delivering payload MD

operation upgradeCustomer
  expecting payload "promotionCode": P // placeholder
  delivering payload P // response unspecified

Providers and Protocol Bindings (HTTP, Other Technologies)

MDSL by design generalizes and abstracts from concepts in other API contract languages. This is rather straightforward for most of them (and has been done before in other interface definition languages). For HTTP resource APIs, additional concepts and an intermediate step are required because MDSL endpoints do not map to resources and their URIs one-to-one. In particular, dynamic endpoint addressing, as promoted by RFC6570 “URI Templates” [Fielding 2012] and used in HTTP path parameters, is specific to HTTP. Moreover, it is not obvious how to express complex request payloads of retrieval operations—HTTP GET and request bodies do not go well together.³ HTTP also handles addressing, request and response parameters, errors, and security concerns in specific ways (for good reasons).

The missing mapping information can be specified in an explicit provider-level HTTP binding:

Click here to view code image

API provider CustomerRelationshipManagerProvider version "1.0"
offers CustomerRelationshipManager
  at endpoint location "http://localhost:8080"
via protocol HTTP binding
  resource CustomerRelationshipManagerHome
    at "/customerRelationshipManagerHome/{customerId}"
    operation createCustomer to PUT // POST taken
      element "customerRecord" realized as BODY parameter
    // no GET yet
    operation upgradeCustomer to PATCH
      element "promotionCode" realized as BODY parameter
    operation deleteCustomer to DELETE
      element "customerId" realized as PATH parameter
    operation validateCustomerRecord to POST
      element "customerRecord" realized as BODY parameter
provider governance TWO_IN_PRODUCTION

To generate OpenAPI and, later on, server-side stubs and client-side proxies from MDSL specifications, not all of the required binding information can be derived from the abstract endpoint types. A particularly important example is the mapping of MDSL operations to HTTP verbs such as GET, POST, PUT, and so on. Hence, additional mapping details, for instance, whether a payload parameter is transferred in the QUERY string or the message BODY (or the URI PATH or a HEADER or a COOKIE), can also be provided (as motivated earlier). Error reports and security policies can also be bound, and media type information can be provided.

3. The protocol specifications are not fully explicit and precise here; that said, many tools and protocol runtimes do not support this combination.

See “Protocol Bindings for HTTP, gRPC, Jolie, Java” in the online language specification for more explanations [Zimmermann 2022].