Home — Endpoint Type — Data Types — Provider and Client — Bindings — OpenAPI generator — Tools Overview

Advanced Support for HTTP Resource APIs

Note: This is an technology preview subject to change at any time. Its documentation is work in progress. Please refer to the specification of general HTTP protocol binding concepts for context information.

Context

Web API come on different levels of support for REST; hence, it is not clear what is meant by the term “REST API”:

• Hypertext as the engine of application state, sometimes abbreviated HATEOAS, is one of the defining principles of the REST style.
• There are four REST Maturity Levels; HATEOAS support is required to get to the highest level 3. Only “RESTful HTTP APIs” on maturity level 3 should be REST APIs; APIs on other levels can be called “HTTP APIs, “HTTP resource APIs”, or “Web APIs”.
• The book “REST in Practice” provides an example of a REST level 3 hypermedia API called “RESTBucks”, inspired by the IEEE Software article “Your Coffee Shop Doesn’t Use Two-Phase Commit”.
• Subbu Allamaraju called for and outlined contract language support in “Describing RESTful Applications”, and provided another example.
• OpenAPI supports Link Objects, which have sinilar design goals.

MDSL and OpenAPI support maturity levels 1 and 2; this preview describes emerging REST level 3 support in MDSL:

• A link type concept is introduces on the endpoint type level.
• HTTP bindings can wrk with multiple resources and bind them in the ways required for level 3: hyperlinks bind the abstract link concept and add media type information (among other things).

This page explains the two concepts, for the time being by way of example only.

Links in Abstract Contract

MDSL operations can return abstract links in their delivering payload:

API description SimpleHypermediaAPI 

data type HALInstance1 {"someMoreILinkInformation":D<string>}
data type HALInstance2 {"evenMoreILinkInformation":D<string>}

relation type InternalStateTransferLink1 targets HypermediaDrivenEndpoint action continueProcessing input HALInstance1 // DAP (RiP)
relation type InternalStateTransferLink2 targets HypermediaDrivenEndpoint action terminate input HALInstance2 // action: operation or free-form
relation type ExternalStateTransferLink targets external resource at "http://map.mdsl.hateoas/elsewehere"

endpoint type HypermediaDrivenEndpoint
  serves as PROCESSING_RESOURCE
  exposes
    operation initiateProcess with responsibility STATE_CREATION_OPERATION
      expecting
        payload "in":D<string>
      delivering
        payload "out":D<int>
        links 
         "transferToStep2": InternalStateTransferLink1 
      
    operation continueProcessing with responsibility STATE_TRANSITION_OPERATION
      expecting
        payload "id2" 
      delivering
        payload {"statusCode":D<int>}
        links 
          "self": InternalStateTransferLink1
          "finishProcessing": InternalStateTransferLink2 
          "goElsewhere": ExternalStateTransferLink               

HTTP Binding Extensions

On the tecnology binding level, the abstract links become “DAPs”, i.e., typed links that define taregt URI, HTTP verb and media type (there are several options for providing this information):

API provider RESTLevel3Provider
  offers HypermediaDrivenEndpoint
  at endpoint location "http://map.mdsl.hateoas"
  via protocol HTTP
   static binding
    resource Home at "/home"
     
      media type CustomMediaTypeRepresentationJSON as "application/vnd.step2cmt+json"
      relation type InternalStateTransferLink1 to {ResourceForStep2, PUT, CustomMediaTypeRepresentationJSON} 
                
      operation initiateProcess to POST
        // all elements realized as QUERY parameters
        // element "in" realized as PATH parameter // OAS/Swagger editor warns if not in URI
        element "in" realized as COOKIE parameter // 2nd one and all others ignored (ok)
        // element "in" realized as HEADER parameter 
        // element "in" realized as BODY parameter
        // element "in" realized as QUERY parameter // default
    
        accepts CustomMediaTypeRepresentationJSON 
        replies "application/vnd.restbucks.order-payment+json" 
    
    resource ResourceForStep2 at "/home/{id}"
      
      media type ProcessTerminationInformation as "application/vnd.myHALinstance+json" 
      relation type InternalStateTransferLink2 to {Home, PUT} // CMT not defined here for GET on "/home/{id} 
      relation type ExternalStateTransferLink to {"SomeExternalResource", POST, ProcessTerminationInformation} 
      
      operation continueProcessing to PUT
        element "id2" realized as PATH parameter // OAS/Swagger editor warn if not in URI
        // no accepts/replies here (link is enough)

Note that this endpoint provider instance defines tw resources to bind a single endpoint type.

Status and Limitations

As a technology preview, this feature might change at any time, both on the language and on the tool level. And it still specifies static contracts, whereas the original vision of REST promotes dynamic contracts in support of flexibility and evolvability.

The OpenAPI generator is able to convert the above information into Link Objects as defined in the OpenAPI specification. The processing of these Link Object differs in the tools processing OpenAPI as input.

More information

Several versions of the RESTBucks example have been modeled in MDSL (see JUnit test cases of the project).

Site Navigation

Language specification pages:

• Service endpoint contract types
• Data contracts (schemas)
• General HTTP protocol binding concepts (and bindings to other technologies)
• Other runtime concepts
• OpenAPI generator

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