View on GitHub

MDSL

A domain-specific language to specify (micro-)service contracts and their data representations (realizing the API Description pattern from MAP)

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

Note: Work in progress still, especially the gateway part; subject to change at any time!

The language concepts described there 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).

API Provider

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

API provider sampleProviderTemplate
offers sampleContractTemplate
at endpoint location "http://www.tbc.io:80/path/subpath"
via protocol RESTful_HTTP // or other supported protocol
under conditions "See http://www.tbc.io/terms-and-conditions.html"
evolution governance AGGRESSIVE_OBSOLESCENCE

At present, the following protocols are predefined:

RESTful_HTTP SOAP_HTTP gRPC Avro_RPC Thrift AMQP

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 SampleAPIProvider1 
  offers PatternStereotypesDemoContract 
    at endpoint location "http://www.testdomain.io:80/path/subpath"
    via protocol RESTful_HTTP   
  	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.

API Client

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

API client SampleAPIClient
  consumes contractTemplate
  from providerTemplate
  via protocol RESTful_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
  exposes CustomerManagementContract
  at endpoint location "ExternalURI"
  via protocol SOAP_HTTP

  consumes CustomerManagementContract2 
  from SampleAPIProvider1
  via protocol gRPC

Service Composition

It yet has to be decided if and how such concepts should be introduced into MDSL; many such languages have already been defined in the workflow/BPM and programming languages communities.

Service endpoint contract types and data contracts (schemas).

Quick reference.

Back to MDSL homepage.

Copyright: Olaf Zimmermann, 2019. All rights reserved.

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