You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -40,15 +40,15 @@ These two languages can be used independently of each other; for instance, data
40
40
## Getting Started
41
41
42
42
* Presentations featuring Context Mapper, MAP and MDSL can be found [here](https://ozimmer.ch/papers/).
43
-
* The [GitHub Pages for MDSL](https://microservice-api-patterns.github.io/MDSL-Specification) provide a tutorial and language reference information.<!-- * There is a [Project Wiki](https://github.com/Microservice-API-Patterns/MDSL-Specification/wiki/Getting-Started-with-MDSL), which is not populated much (yet) and not kept up to date as much as the GitHub pages. -->
43
+
* The [GitHub Pages for MDSL](https://microservice-api-patterns.github.io/MDSL-Specification) provide a tutorial and language reference information.
44
44
* There is an [Eclipse update site](https://microservice-api-patterns.github.io/MDSL-Specification/updates/) for the MDSL editor.
45
45
* All generators are available via a Command Line Interface (CLI) now; see [this readme](./dsl-core/io.mdsl.cli/README.md) and [these examples](./examples/mdsl-standalone-example).
46
46
* As a contributor, please consult the [readme file of the dsl-core](./dsl-core/README.md) project for getting started information and prerequisites.
*[Data types](https://microservice-api-patterns.github.io/MDSL-Specification/datacontract) (a.k.a. published language)
@@ -62,6 +62,7 @@ These two languages can be used independently of each other; for instance, data
62
62
This repository contains:
63
63
64
64
*[dsl-core](dsl-core), the DSL project, Xtext grammar and everything else needed to build an Eclipse plugin providing a MDSL editor.
65
+
<!-- * An older, not fully equivalent version of the grammar in [this folder](antlr4). -->
65
66
* Various [examples](examples).
66
67
* The [sources of the GitHub pages](docs) for MDSL.
67
68
* Some [background information](background) on other IDLs and related projects.
@@ -73,8 +74,15 @@ If you want to contribute to MDSL, you have to clone this repo and generate the
73
74
74
75
## Change Log
75
76
76
-
The current version of MDSL is 4.2. See [change log](changelog.md) for an evolution history; see GitHub [release notes](https://github.com/Microservice-API-Patterns/MDSL-Specification/releases) for additional update information.
77
+
The current version of the MDSL language is 5.0; the tool version is 5.0.1. This MDSL version extends service contracts with support for events, states, flows, compensation. It also supports true REST level 3 concepts both on the abstract endpoint type level and in the redesigned bindings.
77
78
79
+
See [change log](changelog.md) for an evolution history; see GitHub [release notes](https://github.com/Microservice-API-Patterns/MDSL-Specification/releases) for additional update information.
80
+
81
+
<!--
82
+
A possible roadmap for language and tools is (subject to change at any time):
83
+
84
+
* to be continued
85
+
-->
78
86
79
87
## Context Information: MAP and Xtext
80
88
@@ -84,7 +92,7 @@ All [Microservice API Patterns (MAP)](https://microservice-api-patterns.org/) ar
84
92
* As enums for roles and responsibilities
85
93
* As stereotypes annotating representation elements
86
94
87
-
See ["MAP Decorators" section of the MDSL tutorial](https://github.com/Microservice-API-Patterns/MDSL-Specification/tutorial) for more information. <!-- TODO copy one-pager in SummerSoC paper to GitHub pages or elsewhere in repo -->
95
+
See ["MAP Decorators" section of the MDSL tutorial](https://microservice-api-patterns.github.io/MDSL-Specification/tutorial) for more information. <!-- TODO copy one-pager in SummerSoC paper to GitHub pages or elsewhere in repo -->
88
96
89
97
The MDSL grammar, to be found in src folder of the `dsl-core/io.mdsl` project, was originally developed with Eclipse Photon (4.8.0) and Xtext (2.14) as provided by the Eclipse Modeling Platform. MDSL makes use of the referencing feature in Xtext ('name' attribute). Future work is required to also support this technology in other IDEs (such as Visual Studio Code).
Copy file name to clipboardExpand all lines: changelog.md
+56-2
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,14 @@
2
2
3
3
Also see GitHub [release notes](https://github.com/Microservice-API-Patterns/MDSL-Specification/releases).
4
4
5
+
V5.0, December 2020
6
+
7
+
* Extended HTTP binding: new resource concept, media types, security policies, (error, status) reporting, HATEOAS links (technology preview)
8
+
* Refactored and adopted oasgen tool accordingly: now featuring default and fully flexible verb-parameter mappings, improved naming heuristics, deep query objects; server instance, header payload mapped (still some documented known limitations)
9
+
* New binding-level validators (more in the backlog)
10
+
* Experimental/preview support for events, states, flows
11
+
* Grammar cleanup (working around XText limitation: <https://www.eclipse.org/forums/index.php?t=msg&th=877258&goto=1494895&#msg_1494895>)
// technology-neutral error reporting (to be bound to OAS/HTTP, gRPC, Java, Jolie):
34
-
reporting error "DuplicateEntry": D<string>
37
+
reporting error DuplicateEntry D<string>
35
38
// technology-neutral security policy (to be bound to protocols and platforms):
36
-
protected by policy "UserIdPassword":{"userId":ID<string>, "password":MD<string>}
39
+
protected by policy BasicAuthentication "UserIdPassword":{"userId":ID<string>, "password":MD<string>}
37
40
operation updatePrice /* optional: "in REQUEST_REPLY conversation" */
38
41
expecting payload "price": Money
39
-
delivering payload D<void>
40
-
// not delivering any payload, just a transport-level status code (?)
42
+
// delivering payload D<void>
43
+
// not delivering any payload, just a transport-level status code
41
44
~~~
42
45
43
46
44
47
## HTTP Protocol Binding
45
48
46
49
HTTP handles addressing, request and response parameters, errors, and security concerns in certain ways (for good reasons). The protocol design deviates from than of most interface definition languages and "RPC-ish" communication protocols. To generate OpenAPI and, later on, server-side stubs and client-side proxies from MDSL specifications, some of the required information can therefore always be derived from the abstract endpoint types. A primary example is the mapping of MDSL operations to HTTP verbs/methods such as GET, POST, PUT etc.
47
50
48
-
The additional information can be specified in a provider-level *binding*:
51
+
The additional information can be specified in a provider-level *HTTP binding*:
49
52
50
53
~~~
51
54
API provider ProductManagementWebServiceProvider
52
55
offers ProductManagementService
53
56
at endpoint location "http://www.tbc.io:80/path/subpath"
54
-
via protocol HTTP
57
+
via protocol HTTP
55
58
binding
56
-
operation define to POST at "/products/{productId}" // PATH parameter (implicit)
57
-
element productDescription realized as BODY parameter
58
-
element successAck realized as BODY parameter // only possibility for response payload element
59
-
report DuplicateEntry realized as 412 with ErrorReport
60
-
policy UserIdPassword realized as BASIC_AUTHENTICATION
61
-
// media types (defined in several RFCs, see https://en.wikipedia.org/wiki/Media_type)
62
-
accepts application/json // defined at https://www.iana.org/assignments/media-types/media-types.xhtml
63
-
replies "application/custom-mediatype-for-productDTO-v1" // custom media type (recommended REST practice)
59
+
resource PMSResource at "/products/{productId}" // PATH parameter (implicit)
60
+
operation define to POST
61
+
all elements realized as BODY parameters
62
+
report DuplicateEntry realized as 412 with "DuplicateEntry"
63
+
policy BasicAuthentication realized as BASIC_AUTHENTICATION
64
+
accepts "application/json"// defined at https://www.iana.org/assignments/media-types/media-types.xhtml
65
+
replies "application/vnd.custom-mediatype-for-productDTO-v1" // custom media type
66
+
64
67
operation updatePrice to PATCH at "/products/{productId}/price"
65
-
element money realized as BODY parameter
68
+
element "currency" realized as QUERY parameter
69
+
element "amount" realized as QUERY parameter
66
70
~~~
67
71
68
-
*Important note*: This binding is work in progress and yet has to be completed and fully validated. For instance, the parameter mappings to path, query, form/body and cookie parameters is not fully implemented in the current MDSL tools yet.
72
+
The information in the binding refers to and refines the operation- and message level specification (abstract endpoint type level:)
73
+
74
+
* At least one resource must/can be defined (`PMSResource`); their names and URIs must differ.
75
+
* The resource URIs may contain URI name templates /`{productId}`).
76
+
* The operations from the references endpoint type can be bound in multiple resources (once each). The operation-to-verb assignment (`POST`, `PATCH`) must be unique in each resource.
77
+
* The representation elements from request payloads of operations can be mapped to HTTP parameter types jointly (`all elements realized as BODY parameters`) or individually (`element "currency" realized as QUERY parameter`). Default are in place (see [here](./tools/generators/open-api)). There are some limitations of flat/nested tree usage; cardinalities (`?`, `*`, `+`) are respected, though.
78
+
* The abstract error/status reporting is mapped to HTTP codes (`report DuplicateEntry realized as 412 with "DuplicateEntry"`). In our MDSL tools, a validator checks that only existing reports are bound.
79
+
* Security policies are bound and mapped in the same way (`policy BasicAuthentication realized as BASIC_AUTHENTICATION`).
80
+
* One or more MIME types of request and response messages can be defined (`accepts`, `replies`). Both standard and custom media types can be specified.
81
+
* Not shown in the above example, but explained [here](./http-rest), links are mapped to OpenAPI [link objects](https://swagger.io/docs/specification/links/) and, in turn hypermedia links in response messages.
82
+
* Server instances are created for the endpoint addresses.
83
+
84
+
*Status update*: This is the first complete version of the binding. It is implemented in the current [MDSL tools](./tools), but has not been fully validated yet. The tool implementation has some known limitations.
69
85
70
86
71
87
## gRPC Protocol Buffers Binding
@@ -117,8 +133,7 @@ API provider ProductManagementJavaServiceProvider
117
133
element money realized as boolean type
118
134
~~~
119
135
120
-
In the current release, only the package name is used.
121
-
<!-- there is an unfinished Freemarker template; /* [Q]: "extends"? */ -->
136
+
In the current release, only the package name is used. <!-- there is an unfinished Freemarker template; /* [Q]: "extends"? */ -->
122
137
123
138
124
139
## Other Bindings
@@ -141,8 +156,6 @@ Language specification pages:
141
156
*[Data contracts (schemas)](./datacontract)
142
157
* Other [runtime concepts](./optionalparts)
143
158
144
-
[Quick reference](./quickreference). [Tutorial](./tutorial). [Tools](./tools). Back to [MDSL homepage](./index).
145
-
146
159
*Copyright: Olaf Zimmermann, 2018-2020. All rights reserved. See [license information](https://github.com/Microservice-API-Patterns/MDSL-Specification/blob/master/LICENSE).*
Copy file name to clipboardExpand all lines: docs/datacontract.md
+3
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,8 @@ author: Olaf Zimmermann
4
4
copyright: Olaf Zimmermann, 2019-2020. All rights reserved.
5
5
---
6
6
7
+
[Home](./index)—[Endpoint Type](./servicecontract)—[Provider and Client](./optionalparts)—[Bindings](./bindings)—[Tutorial](./tutorial)—[Cheat Sheet](./quickreference)—[Tools](./tools)
8
+
7
9
Data Contracts and Schemas in MDSL
8
10
==================================
9
11
@@ -15,6 +17,7 @@ MDSL aims at supporting agile modeling. Any service API exposes a published lang
15
17
* Service Level Objectives (SLOs) and/or Service Level Indicators (SLIs) that are part of [Service Level Agreements (SLAs)](https://microservice-api-patterns.org/patterns/quality/qualityManagementAndGovernance/ServiceLevelAgreement)
16
18
* Data Transfer Objects (DTOs) or, more precisely, Data Transfer Representations (DTRs)
Copy file name to clipboardExpand all lines: docs/examples.md
+12-5
Original file line number
Diff line number
Diff line change
@@ -4,11 +4,13 @@ author: Olaf Zimmermann
4
4
copyright: Olaf Zimmermann, 2019. All rights reserved.
5
5
---
6
6
7
-
MDSL Grammar Example
8
-
====================
7
+
[Home](./index)—[Endpoint Type](./servicecontract)—[Data Type](./datacontract)—[Provider and Client](./optionalparts)—[Bindings](./bindings)—[Cheat Sheet](./quickreference)—[Tools](./tools)
9
8
10
9
11
-
## Service Contract
10
+
MDSL Examples
11
+
=============
12
+
13
+
## Service Contract (Grammar Reference)
12
14
The following exemplary API specification compiles against the [MDSL grammar](https://github.com/Microservice-API-Patterns/MDSL-Specification/blob/master/dsl-core/io.mdsl/src/io/mdsl/APIDescription.xtext):
13
15
14
16
<!-- TODO feature error reporting and versioning of data types -->
@@ -50,7 +52,7 @@ endpoint type CustomerManagementContract
50
52
51
53
<!-- some text from service contract page could be copied or moved here -->
52
54
53
-
## Data Contract
55
+
## Data Contract Examples
54
56
55
57
The following simple examples feature the structural language primitives and give instantiation examples (in the comments):
56
58
@@ -70,9 +72,14 @@ data type TwoNestingLevels {SomeStructuredRecord, SomeAtomicParameter}
70
72
data type SomeFlatRecord (D<string>, D<int>, D<bool>)
71
73
// yields ("A", 1, true)
72
74
73
-
data type ChoiceDemo {"optionA":D | "optionB":D}
75
+
data type ChoiceDemo {"optionA":D | "optionB":D} // not implemented in tools yet
0 commit comments