View on GitHub

Microservice DSL (MDSL)

A Domain-Specific Language (DSL) to specify (micro-)service contracts, their data representations and API endpoints.

Home — Endpoint Type — Data Type — Bindings — Tutorial — Cheat Sheet — Tools

Runtime Language Concepts: API Provider, API Client, API Gateway

Note: Work in progress still (the protocol bindings in particular)!

The language concepts described here can be used for context mapping, deployment modeling, and code generation (e.g., walking provider skeletons, test clients). Unlike endpoint types and data contracts, they play on the “instance” rather than the “class” level (just like ports in WSDL are instances of port types).

We assume this simple contract to exist (note that this example also feature the optional, global overview description):

API description HelloWorldDemoAPI
overview "Demonstrating optional/runtime concepts"

endpoint type SomeDemoContract
exposes 
  operation sayHello 
    expecting payload D<string>  
    delivering payload D<int>

API Provider

An API provider exposes one or more endpoint contracts at an address that understands a particular platform-specific protocol:

API provider SampleProvider
offers SomeDemoContract
at endpoint location "http://www.tbc.io:80/path/subpath"
via protocol HTTP binding resource Home // or other supported protocol
under conditions "See http://www.tbc.io/terms-and-conditions.html"
provider governance AGGRESSIVE_OBSOLESCENCE

At present, the following protocols are predefined:

HTTP SOAP_HTTP gRPC Java

It is also possible to define a custom protocol by including its name in double quotes: "Some other protocol".1

Optionally, providers can disclose terms and conditions for API usage or a Service Level Agreement (SLA) as well as their approach to versioning and evolution.

A more complete example, also featuring an SLA and evolution governance information, looks like this:

API provider SampleProvider 
  offers SomeDemoContract 
    at endpoint location "http://www.testdomain.io:80/path/subpath"
    via protocol HTTP binding resource SampleAPIProvider1Resource
  	with endpoint SLA // provider1Endpoint1SLA
      type QUANTITATIVE // optional now
    	objective performanceSLO1 "responseTimeUnder" 5 seconds
    	penalty "If the SLA is not met, the penalty is ..."
    	notification "To report SLA violations, you have to ..."
    	rate plan USAGE_BASED
    	rate limit MAX_CALLS 5 within 24 hours
    endpoint governance AGGRESSIVE_OBSOLESCENCE
  with provider SLA // provider1SLA
  type QUALITATIVE
  objective performanceSLO2 "availability" 
     100 "every commercially reasonable effort, but not guaranteed"
  provider governance TWO_IN_PRODUCTION

The language elements in the endpoint and provider SLA sections model the elements an SLA is supposed to contain according to the SLA pattern page on the MAP website.

Protocol Bindings

A provider must provide at least oen binding. See bindings page for further information.

API Client

The consumers of endpoint contracts (API clients) are modeled according to the following template:

API client SampleAPIClient
  consumes SomeDemoContract
  from SampleProvider
  via protocol HTTP

Clients merely have to decide which APIs to consume and which protocol to use to do so.

API Gateway

API gateways are hybrid providers (in upstream role) and clients (downstream role):

API gateway SampleAPIGatweway
  offers SomeDemoContract
  at endpoint location "ExternalURI"
  via protocol SOAP_HTTP

  consumes SomeDemoContract 
  from SampleProvider
  via protocol gRPC

API Provider Implementation

An API provider has an upstream interface (see bindings), but also a downstream implementation (which is not visible to its external client, but still worth specifying internally):

ProviderImplementation:
	'API' 'provider' 'implementation'
	name=ID
	'realizes' upstreamBinding=[Provider]
	'in' platform=ImplementationTechnology
	('as' class=STRING ('extending' superclass=STRING)? // default assigned if not specified
;

enum ImplementationTechnology: PlainJava | SpringMVC | STRING // more to be added
;

An example of an instance of such provider binding is:

API provider implementation SampleAPIProvider1Impl 
  realizes SampleAPIProvider1
  in PlainJava
  as "co.something.model.SomeClassName" extending "Entity"
  // or: with binding SomeJavaBinding (if defined)

These language concepts (provider bindings and their implementations) can be used for context mapping, deployment modeling, and code generation (e.g., walking provider skeletons and test clients). Unlike endpoint types and data contracts, they play on the “instance” rather than the “class” level (just like ports in WSDL are instances of port types).

Site Navigation

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

  1. In this case, future MDSL tools cannot be expected to be able to process the specification fully (unless a suited plugin is available). ↩