MAPDecoratorUsageReference.mdsl

/* 
 * payload [ {ptree1}, {ptree2} ] // Parameter Forest
 * payload {{subtree1},{subtree2}, {apl},{ap}} // Parameter tree (can also appear in pforest)
 * payload (apl) // Atomic Parameter List (can also appear in ptree) 
 * payload ap // Atomic Parameter (can also appear in ptree and apl) 
 * 
 * AP syntax:
 * <<pattern>>"name":Role<Type> // pattern stereotype, name and type are optional; stereotype can also be assigned to other tree nodes (apls and ptrees)
 *  
 * */

API description AllPatternsInActionDemo
version "1.0.0"
usage context SOLUTION_INTERNAL_API for BACKEND_INTEGRATION

// data type Entity1 (ID,D) // how about ", ..." as a placeholder for iteration/recursion, tbd TODO

// TODO (v4.1) AsyncAPI generator has problems with some APLs (partially specified ones, with certain cardinalities), can use PTs instead

// feature struct patterns as data types so that newbies do not get overwhelmed by big picture operations
data type SampleAtomicParameter "sap":D<string>
data type SampleAtomicParameterList ("ap1":D<int>,"ap2":D<string>)
data type SampleParameterTree {{P},{"ap1":D<int>,"ap2"}}
data type SampleParameterForest [{P};{P}]

data type SampleAtomicParameter1 "sap":D<string>
data type SampleAtomicParameterList1 ("someID":ID*,"someData":D)
data type SampleParameterTree1 {{P}, {SampleAtomicParameterList1}}
data type SampleParameterForest1 [{P}; {SampleParameterTree1}]

data type BooleanExpression version "1" D<bool>
data type UUID version "0.1" D<int>
data type SharedContext version "0.1.1" {"api Key":UUID?, "session Id":D<int>?, "otherQoSPropertiesThatShouldNotGoToProtocolHeader":D<string>*}
data type Page ("data":D*|"link":L*) // a page either is a set of value parameters or a set of links
data type PersonalData <<Entity>>D
data type Address <<Entity>>D
data type CustomerEntity {{PersonalData}, {Address}}

data type NN "parameter_tree":{{D<int>}, (D<int>)}

data type CustomerWithAddressAndMoveHistory { 
    <<Entity>>"CustomerCoreData":D, 
    "AddressRecords":Address+, // one or more
    "MoveHistory": PersonalData* // type reference
} 

data type SampleJolieMapping "tbc"
data type SampleYAMLMapping "customer: {name: string, address: E}"
data type SampleYAMLSequence "- customerList: {name: string, address: E}"

data type SOAPFaultDataRepreentation {"code":D<int>, "string": D<string>, "actor":D<string>, "detail":D<string>}

endpoint type PatternStereotypesDemoContract
  version "1.0" 
  serves as INFORMATION_HOLDER_RESOURCE role
  // identified by ("id":D<int>, "filter":D<string>) // needed for URI templating (SOAP: turn into top-level XML element "(elementParams, opParams)"?)
  // identified by {"id", "filter"} // needed for URI templating (SOAP: turn into top-level XML element "(elementParams, opParams)"?) linter needs to catch usage of PF, nested PT!
  exposes 
      operation testOpEverythingButRequestBundle
	  with responsibility RETRIEVAL_OPERATION
	  expecting
	    headers {"header1":D<int> | "header2":D<string>}
	  	payload {
	  			{<<Request_Condition>> BooleanExpression},
	  			{<<Context_Representation>>{
	  					{{<<Wish_List>>"desiredAttributes":D<string>+} | {<<Wish_Template>>"mockTree":SampleParameterTree}} // could also place WL on same level as CR, "|" is XOR cardinality (experimental)
	  				} 
	  			},
	  			{"payload1":SampleParameterTree} // links to Structure patterns category
	  	}+
	    structured as MAP_TYPE
	  delivering
		payload {
				{<<Context_Representation>>SharedContext},
				{<<Pagination>>"payload2":Page, "metadata":MD*, "previousPage":Page?, "nextPage":Page?}	
		} structured as MAP_TYPE
	  reporting 
	  	  error NotFound D<bool>
	  	  error GeneralError D<string>
	  	  error Unauthenticated
	  	  error Unknown P
	  	  error Code D<int>
	  	  error MAPDecoratedReport {<<Error_Report>>("errorCode":D<int>, "errorMessage":D<string>)}+
	  	  analytics OtherReport "tracking": ID // experimental; "status" also available

  	operation testOpEverything
	  // with responsibility CRUD // CRUD no longer supported   
	  expecting
	  	payload <<Request_Bundle>> [
	  		{ // one tree per bundle element
	  			{<<Request_Condition>>D},
	  			{<<Context_Representation>>{
	  					{{<<Wish_List>>D} | {<<Wish_Template>>D}} // could also place WL on same level as CR, "|" is XOR cardinality (experimental)
	  				}
	  			},
	  			{"payload":SampleParameterTree} // links to Structure patterns category
	  		}+ // at least one element in bundle, so + cardinality
		]
	    structured as MAP_TYPE
	  delivering
		payload [ // because request is a bundle ] // add a stereotype Response_Bundle that also links to Request Bundle pattern as we do not have a Response Bundle Pattern 
				{<<Context_Representation>>D};
				{"payload":P}; 
				{<<Error_Report>>("errorCode":D<int>, "errorMessage":D<string>)}+
				
				// TODO add pagination here too?
		]
		structured as MAP_TYPE
		reporting 
			error InternalServerError D<int> // binding to 500
			error BadRequest D<int> // binding to 400
			error NotFound <<Error_Report>>"resource not found": {"errorCode":D<int>, "errorMessage":D<string>}+	
			error NotAllowed <<Error_Report>>{("402":D<int>, "notAuthorized":D<string>) | ("403":D<int>, "anotherMessage":D<string>)}	
			error SOAPFaultReport SOAPFaultDataRepreentation
			analytics MetricsReport "usage statistics": P

	    
  	operation testOpJolieYaml
	  expecting
	  	payload SampleJolieMapping
	    structured as JOLIE_TYPE
	  delivering
		payload SampleYAMLSequence
	    structured as OTHER // "YAML_RX"	   
	    
endpoint type CustomerInformationHolderService serves as INFORMATION_HOLDER_RESOURCE 
  exposes 
    operation getCustomerAttributes
	  expecting
		payload
		{ <<Context_Representation>> 
		  { 
	  	    {<<Annotated_Parameter_Collection>>"qosControl": SharedContext},
	  	  	{<<Wish_List>>"desiredAttributes":ID<string>+}
	  	  }, // end of context representation
	      {
	        "actualPayload":D // <"SomeInParameters">
	      } // end of actual/inner payload
	    } // end of entire/outer payload
	  delivering
		payload {
		  <<Context_Representation>> {
		    {SharedContext},
			{<<Error_Report>>("errorCode":D<int>, "errorMessage":D<string>)}
		  },
		  {<<Pagination>>(
			 "thisPageContent":D, // <"SomeOutParameterSet">,  
			 "previousPage":ID?, 
			 "nextPage":ID?)
		  }		
		}
    operation getCustomerAttributesWithWishlist
	  expecting
		payload { 
	  	  	{<<Wish_Template>>"mockObject":CustomerEntity},
	      {
	        "actualPayload":D // <"SomeInParameters">
	      } // end of actual/inner payload
	    } // end of entire/outer payload
	  delivering
		payload {
		  {<<Entity>> CustomerEntity*
		  }		
		}		
// end of contract

// TODO feature Identifier, Link, Metadata stereotypes 

// TODO feature Embedded Information Holder, Linked Information Holder
	   
API provider SampleAPIProvider1 
  offers PatternStereotypesDemoContract 
    at endpoint location "http://www.testdomain.io:80/path/subpath?p1=v1&p2=v2"
    via protocol HTTP binding resource SampleAPIProvider1HomeResource
  	with endpoint SLA // provider1Endpoint1SLA
      type QUANTITATIVE // optional now
    	objective performanceSLO1 "responseTimeUnder" 5 seconds // "in 80% of calls)"
    	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
                  
IPA // end of API specification