RAPID Resource API Design Language

Transcription

1 RAPID Resource API Design Language Pushing the limits of language usability with XText TED EPSTEIN, FOUNDER AND CEO TANYA FESENKO, LEAD DEVELOPER EclipseCon NA 2015, Xtext Day COPYRIGHT 2015, MODELSOLV, INC. ALL RIGHTS RESERVED. 1

2 Overview RepreZen: solving API interoperability Challenge: a better API description language RAPID Language Features Optional Fluency: accommodating coding styles Keyword Sequence: encourage, don t Enforce Indent-Based Block Scoping: life without curly braces Implementation Overview Summary Q&A COPYRIGHT 2015, MODELSOLV, INC. ALL RIGHTS RESERVED. 2

3 The Elevator Pitch / Unify Data Models / Federate APIs / Integrate Faster COPYRIGHT 2015, MODELSOLV, INC. ALL RIGHTS RESERVED. 3

4 The Elevator Pitch Make Canonical Data Models Practical Frequently recommended, hard to implement Current reality: much easier to build from scratch than to reuse existing data models We want to change that! Enable Highly Interoperable APIs Significantly Lower Long- Term Integration Cost COPYRIGHT 2015, MODELSOLV, INC. ALL RIGHTS RESERVED. 4

5 The Elevator Pitch Make Canonical Data Models Practical Frequently recommended, hard to implement Current reality: much easier to build from scratch than to reuse existing data models We want to change that! Enable Highly Interoperable APIs Reusable data models: business-oriented, technology-independent, semantically rich Allow variability through realization Message payloads still conform to canonical model Property Subsets Significantly Lower Perspective Long- Term Integration Cost Metadata <party datasource= MSDB > <partyid>123</partyid> <partyname xsi:nil= true nullvalue= Not Available /> <accounts> <account datasource= A2 transtype= insert > <accountid>xyz</accountid> <balance xsi:nil= true isrestricted= true /> </account> </accounts> </party> Contextual Constraints COPYRIGHT 2015, MODELSOLV, INC. ALL RIGHTS RESERVED. 5

6 Make Canonical Data Models Practical Frequently recommended, hard to implement Current reality: much easier to build from scratch than to reuse existing data models We want to change that! Enable Highly Interoperable APIs Reusable data models: business-oriented, technologyindependent, semantically rich Allow variability through realization Message payloads still conform to canonical model Significantly Lower Long- Term Integration Cost Service APIs speak the same language Clients can work with multiple APIs, without multiple DTOs, SDKs, etc. Stop runaway spending on remedial integration technology COPYRIGHT 2015, MODELSOLV, INC. ALL RIGHTS RESERVED. 6

7 Changing the way we build APIs Realization This needs to be built into the API modeling language. Representation Business Domain Model Subset Perspective Constraints Metadata Resource Data Model Media Type Format Conventions Hyperlinks Message Schema COPYRIGHT 2015, MODELSOLV, INC. ALL RIGHTS RESERVED. 7

8 Yet Another API Description Language? YAADL? YAAPIDL? There are at least four of these... The nice thing about standards is that you have so many to chose from. - Andrew Tanenbaum If we have to build an API modeling language, it has to be good. and they re pretty good. Web-based editors API Documentation with integrated sandbox Syntax based on YAML or Markdown Interesting language-level reuse REST patterns built in any ideas? COPYRIGHT 2015, MODELSOLV, INC. ALL RIGHTS RESERVED. 8

9 Make it accessible, readable, versatile. Who s going to model these APIs? What she said. Business Analysts Data Professionals Developers! Developers! Developers! and Subject Matter Experts Enterprise Architects COPYRIGHT 2015, MODELSOLV, INC. ALL RIGHTS RESERVED. 9

10 Demo RAPID Usability Features Indent Syntax: Python-like block syntax, no curly braces Advanced highlighting to visualize structure Order Assist: Flexible sequence for declarations Reset to standard sequence using QuickFix or auto-format Optional Fluency Support terse and fluent syntax with optional keywords Semantic highlighting to distinguish optional vs. required keywords COPYRIGHT 2015, MODELSOLV, INC. ALL RIGHTS RESERVED. 10

11 Indent-Based Syntax New Syntax indents define block scope Structural Highlighting - editbox.sourceforge.net Previous Syntax braces for block scoping 11

12 Order Assist 12

13 Optional Fluency Fluent Terse 13

14 Implementation Walkthrough COPYRIGHT 2015, MODELSOLV, INC. ALL RIGHTS RESERVED. 14

15 Work with Xtext Xtext Grammar (*.xtext file) 15

16 Work with Xtext Xtext Grammar (*.xtext file) Generated code (Parser and UI) 16

17 Work with Xtext The rest (customized from generated code) Lexer Formatter Content assist Code Templates Prefs Crossreference Scope Code highlighter Validation/ Quickfix Outline Xtext Grammar (*.xtext file) Generated code (Parser and UI) 17

18 Three features for (each feature): Description Grammar Code Customization 18

19 Feature 1: Automate canonical ordering 19

20 Order Assist methods 20

21 Implementation: Grammar The rest (customized from generated code) Xtext Grammar (*.xtext file) Generated code 21

22 Allow arbitrary order in grammar 22

23 Allow arbitrary order in grammar 23

24 Allow arbitrary order in grammar Disable code-assist and add validator for duplicate singlevalued properties to prevent overriding 24

25 Sort List< INode> Sorting rule: Sequence<GrammarElement> Grammar Tree Compare INodes: Using sorting rules Preserving: List delimiters Whitespaces Attached symbols (*, +) Order of elements of the same kind 25

26 Implementation: Grammar The rest (customized from generated code) Validation Xtext Grammar (*.xtext file) Generated code 26

27 Validation MyJavaValidator # checkmyelement(semanticelement) 27

28 MyJavaValidator # checkmyelement(semanticelement) Validation Semantic Element Syntax Tree Node getincorrectly OrderedChildren() Incorrectly ordered Nodes NodeModelUtils::getNode() 28

29 Implementation: Grammar The rest (customized from generated code) Formatter Xtext Grammar (*.xtext file) Generated code 29

30 Formatter DefaultNodeModelFormatter#format(): 30

31 Formatter DefaultNodeModelFormatter#format(): 31

32 Formatter DefaultNodeModelFormatter#format(): INode: offset text length grammarelement semanticelement 32

33 Formatter DefaultNodeModelFormatter#format(): Writes tokens to character stream and then flushes it The write methods create formatted LineEntries with use of formatter configuration (ElementLocators) 33

34 Formatter DefaultNodeModelFormatter#format(): TextRegion offset and length in the char stream populated in the write methods 34

35 Formatter DefaultNodeModelFormatter#format(): Place for customization 35

36 Implementation: Grammar The rest (customized from generated code) Preferences page Xtext Grammar (*.xtext file) Generated code 36

37 Usability: Preferences 37

38 Testing !=120 How many permutations for five elements? 5 38

39 Testing Xtend Active Annotations 120 green tests! 39

40 Changes: Automate Canonical Ordering The rest (customized from generated code) Enable arbitrary order Validation Formatter Preferences page Xtext Grammar (*.xtext file) Generated code 40

41 Changes: Automate Canonical Ordering Errors for single-value property override Warnings for "incorrect" order The rest (customized from generated code) Validation Formatter Preferences page Xtext Grammar (*.xtext file) Generated code 41

42 Changes: Automate Canonical Ordering The rest Restore (customized from canonical generated order code) Validation Formatter Preferences page Xtext Grammar (*.xtext file) Generated code 42

43 Changes: Automate Canonical Ordering The rest (customized from generated code) enable/disable validation, reordering in formatter Validation Formatter Preferences page Xtext Grammar (*.xtext file) Generated code 43

44 Feature 2: Optional fluency 44

45 What is Optional Fluency? Fluent Terse 45

46 Implementation: Grammar The rest (customized from generated code) Xtext Grammar (*.xtext file) Generated code 46

47 Implementation 47

48 Implementation 48

49 Changes: Optional Fluency The rest (customized from generated code) Optional fluency Xtext Grammar (*.xtext file) Generated code 49

50 Feature 3: Indent-based block scoping in Xtext 50

51 Indent-based block scoping in Xtext With curly braces Python-like notation 51

52 Indent-based block scoping in Xtext Highlighting of boxeseditbox.sourceforge.net 52

53 Implementation: Grammar The rest (customized from generated code) Xtext Grammar (*.xtext file) Generated code 53

54 Grammar NL - newline WS whitespace BEGIN indent END - outdent 54

55 Grammar NL: not hidden NL - newline WS whitespace BEGIN indent END - outdent 55

56 Grammar NL: not hidden NL - newline WS whitespace BEGIN indent END - outdent 56

57 Implementation: Grammar The rest (customized from generated code) Lexer Xtext Grammar (*.xtext file) Generated code 57

58 Custom Lexer Generated / Xtext code Custom code Indent-based Syntax in Xtext - tinyurl.com/pgcowct Insert BEGIN and END token 58

59 Content assist 59

60 Implementation: Grammar The rest (customized from generated code) Content Assist Xtext Grammar (*.xtext file) Generated code 60

61 Custom Lexers Plural now Generated / Xtext code Custom code Content-assist needs its own lexer 61

62 Custom Lexers Generated / Xtext code Custom code 62

63 Content Assist Also see Enhancing Content Assist from XtextCON tinyurl.com/onou2hu 63

64 Content Assist Also see Enhancing Content Assist from XtextCON tinyurl.com/onou2hu 64

65 Content Assist Also see Enhancing Content Assist from XtextCON tinyurl.com/onou2hu 65

66 Content Assist Place for customization 66

67 Content-Assist Context Factory Initialize data Analyze data to create content assist contexts Content Assist Contexts 67

68 Content-Assist Context Factory Syntax tree nodes lastcompletenode, lastvisiblenode, currentnode, datatypenode Semantic model - current model Initialize data Analyze data to create content assist contexts Content Assist Contexts 68

69 Content-Assist Context Factory Start a new token, complete current one, collect available alternatives, etc Initialize data Analyze data to create content assist contexts Content Assist Contexts 69

70 Content-Assist Context Factory Customize to respect indents Initialize data Analyze data to create content assist contexts Content Assist Contexts 70

71 Implementation: Grammar The rest (customized from generated code) Formatter Xtext Grammar (*.xtext file) Generated code 71

72 Formatter Assign correct value to FormattingConfigBasedStream #indentationlevel No line wraps should be introduced by formatter line wraps change structure of Python-like models No spaces around invisible rules synthetic (BEGIN and END) and NL (newline) 72

73 Changes: Indent-based Syntax The rest (customized from generated code) Add BEGIN and END terminal rules Lexer Content Assist Formatter Xtext Grammar (*.xtext file) Generated code 73

74 Changes: Indent-based Syntax Synthesize BEGIN and END tokens The rest (customized from generated code) Lexer Content Assist Formatter Xtext Grammar (*.xtext file) Generated code 74

75 Changes: Indent-based Syntax The Show rest proposals (customized from according generated to code) indent level Lexer Content Assist Formatter Xtext Grammar (*.xtext file) Generated code 75

76 Changes: Indent-based Syntax The rest (customized from generated code) Preserve NLs and indents Lexer Content Assist Formatter Xtext Grammar (*.xtext file) Generated code 76

77 Summary Still an ongoing experiment Early feedback from users has been very positive. We welcome your feedback! API Studio is a commercial product, still pre-launch Offering a free license with 1-year maintenance to Conference attendees (1 per organization) Register at get.reprezen.com with invitation code eclipsecon2015 Contacts: ted.epstein@reprezen.com tatiana.fesenko@reprezen.com COPYRIGHT 2015, MODELSOLV, INC. ALL RIGHTS RESERVED. 77

78 Questions THANK YOU! COPYRIGHT 2015, MODELSOLV, INC. ALL RIGHTS RESERVED. 78