This document discusses metamodeling and metaprogramming approaches for developing client libraries for REST APIs. It presents a metamodel for describing REST APIs and shows how annotations in the xTend language can be used as an alternative internal DSL (domain-specific language) to generate code for a REST client library from descriptions of API requests and resource types. Active annotations are processed by custom compilers and can generate platform-specific code while providing static type safety. Both metamodeling and metaprogramming through active annotations are presented as model-driven approaches for developing web applications and REST client code.

1. ECMFA 2016: Metamodeling vs Metaprogramming
Metamodeling vs Metaprogramming
A Case Study on Developing Client Libraries for REST APIs
Markus Scheidgen
scheidge@informatik.hu-berlin.de
@mscheidgen
Frederik Marticke
marticke@informatik.hu-berlin.de
Sven Efftinge
sven.efftinge@typefox.io
@svenefftinge
1

2. ECMFA 2016: Metamodeling vs Metaprogramming
RESTful Web Applications
Metamodeling vs Metaprogramming
Markus Scheidgen
scheidge@informatik.hu-berlin.de
@mscheidgen
Frederik Marticke
marticke@informatik.hu-berlin.de
Sven Efftinge
sven.efftinge@typefox.io
@sefftinge
2

3. ECMFA 2016: Metamodeling vs Metaprogramming
Agenda
■ Model-driven for Web Applications
■ Representational State Transfer (REST)
■ Metamodeling: external DSL
■ Metaprogramming: Active Annotations
■ Conclusions
3

4. ECMFA 2016: Metamodeling vs Metaprogramming
MDD and WEB REST Metamodeling Active Annotations Conclusions
Web Applications
4
Endpoints
GWT: Java
Javascript
Cloud Storage
e.g. from Google
Hypertext Transfer Protocol (HTTP)
Client
e.g. Web Browser
Server
e.g. App Engine

5. ECMFA 2016: Metamodeling vs Metaprogramming
MDD and WEB REST Metamodeling Active Annotations Conclusions
Web Applications – Horizontal “Platforms”
5
Endpoints
GWT: Java
Javascript
Graph Database
e.g. Neo4J
Servlet: JavaRuby JavascriptPython PHP
Document Database
e.g. MongoDB
Cloud Stoage
e.g. from Google
SQL Database
e.g. MySQL
Hypertext Transfer Protocol (HTTP)
JavascriptJava
e.g. on Android
Objective-C
e.g. on iOS
Dart

6. ECMFA 2016: Metamodeling vs Metaprogramming
MDD and WEB REST Metamodeling Active Annotations Conclusions
Web Applications – Horizontal “Platforms”
6
Endpoints
GWT: Java
Javascript
Graph Database
e.g. Neo4J
Servlet: JavaRuby JavascriptPython PHP
Document Database
e.g. MongoDB
Cloud Stoage
e.g. from Google
SQL Database
e.g. MySQL
Hypertext Transfer Protocol (HTTP)
JavascriptJava
e.g. on Android
Objective-C
e.g. on iOS
Dart

7. ECMFA 2016: Metamodeling vs Metaprogramming
MDD and WEB REST Metamodeling Active Annotations Conclusions
Web Applications – Horizontal “Platforms”
7
Endpoints
GWT: Java
Javascript
Graph Database
e.g. Neo4J
Servlet: JavaRuby JavascriptPython PHP
Document Database
e.g. MongoDB
Cloud Stoage
e.g. from Google
SQL Database
e.g. MySQL
Hypertext Transfer Protocol (HTTP)
JavascriptJava
e.g. on Android
Objective-C
e.g. on iOS
Dart

8. ECMFA 2016: Metamodeling vs Metaprogramming
MDD and WEB REST Metamodeling Active Annotations Conclusions
Web Applications – Vertical “Platforms”
8
Endpoints
GWT: Java
Javascript
Graph Database
e.g. Neo4J
Servlet: JavaRuby JavascriptPython PHP
Document Database
e.g. MongoDB
Cloud Stoage
e.g. from Google
SQL Database
e.g. MySQL
Hypertext Transfer Protocol (HTTP)
JavascriptJava
e.g. on Android
Objective-C
e.g. on iOS
Dart
object.name = “John”
json.put(“name”, “John”);
bean.setName(“John”);
entity.set(“name”,“John”);
{ name : “John” }

9. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
Representational State Transfer (REST)
■ Set of principles for distributed architectures by
Roy Fielding
■ Most importantly: stateless server
■ Allows robust, scalable, easy to build and easy to
maintain server
■ In practice almost always synonymous with web-
services based on HTTP and JSON
■ Examples: Facebook, Twitter, Google+, Youtube, ...
9

10. CLIENT
10
GET
api.twitter.com/1.1/
statuses/user_timeline.json?
screen_name=”mscheidgen”
GET
api.twitter.com/1.1/
statuses/user_timeline.json?
screen_name=”mscheidgen”&
max_id=”37..3”
[
{
id : 123336
text : “Som
favorits : 2
user : {
screen_n
name : “M
follower :
}, ...
}, ...
{
id : 364625
text : “Che
}
]
SERVER
200 OK
[
{
id : 1233364542,
text : “Going to ECMFA; #STAF”,
favorits : 21, retweets = 3,
user : {
screen_name : “mscheidgen”,
name : “Markus Scheidgen”,
follower : 1021, ...
}, ...
}, ...
{
id : 374256453
text : “Check out the new ...”, ...
}
]
reprsentational
state transfer

11. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
11
REST – How it works
■ Identify resources via URLs: host, path, and
parameters
■ CRUD methods, i.e. HTTP’s PUT, GET, POST,
DELETE
■ Resource contents is represented platform
independently as JSON (or XML)
■ HATEOAS: ideally hyperlinks in resources
connect all resources of one service

12. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
REST – Metrics and Flaws
+ HTTP and JSON are platform independent, libraries
for most systems and programming languages exist
- HTTP and JSON represent the smallest common
denominator for most systems and programming
languages
- Loads of platform specific boilerplate code to
process HTTP and JSON
- No static types for URL and JSON data, no static
safety
12

13. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
REST – Client Libraries
13
val request = HTTP.get("api.twitter.com/1.1/"statuses/user_timeline.json")
request.queryString("screen_name", "mscheidgen")
val str = request.asString()
val jsonNode = JSON.parse(str)
val jsonArray = jsonNode.asArray()
for (i:0..<jsonArray.length) {
val jsonItem = jsonArray.get(i);
println(jsonItem.get("text"))
}
val result = twitter.statuses.userTimeline.
userId("mscheidgen").xResult()
for (item:result) {
println(item.text)
}
exists?
right type?
is it an array?
exists/right type?
save

14. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
REST – Client Libraries
■ language specific, uses language features, i.e. type safety
■ turns HTTP request/response RPCs into regular method
calls
■ comprises
■ a method for each API function
■ a wrapper type for each API resource type
■ Client libraries consist of very canonical, schematic
boilerplate code. They are dull, tedious, and error prone to
make.
14

15. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
Code
the desired platform code, e.g.
a REST client library
Code
the desired platform code, e.g.
a REST client library
Code-Generator
a tool that processes a
metamodel instance to
generates code
Code-Generator
a tool that processes a
metamodel instance to
generates code
Platform/
Language
Platform/
Language
Metamodeling
15
Metamodel
defines language constructs,
e.g. constructs to define REST
request and resource types
Model
uses the given language
constructs, e.g. to describe a
REST API
Code-Generator
a tool that processes a
metamodel instance to
generates code
Code
the desired platform code, e.g.
a REST client library
Metametamodel
the metamodeling language
Code-Generator
Language
Platform/
Language

16. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
A Metamodel for REST APIs
16
method:Methods
path:EString
Request
separator:EString
Parameter
PrimitiveDataType
ComplexDataType
Response
Field
GET
POST
PUT
DELETE
«enum»
Methods
type 1
response 1
{subsets features}
pathPattern:EString
PathParameter
baseURL:EString
REST-API
features 0..*
parameters 0..*
{subsets features}
Class
array:EBoolean
Feature DataType
name:EString
NamedElement
0..* parameters
{redefines features} 0..*
dataTypes
0..*
requests
QueryParameter BodyParameter
get request Timeline
for “statuses/user_timeline.json”
returns array of Status {
query max_id : String
query screen_name : String
}
datatype Status {
id : String
text : String
favorits : Integer
retweets : Integer
user : User
}
datatype User {
screen_name : String
name : String
...
}

17. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
xTend
17
@request(path=“statuses/user_timeline.json”,
response=@Response(type=Status, isArray=true))
class Timeline {
String max_id
String screen_name
}
@JSON class Status {
String id
String text
int favorits
int retweets
User user
}
@JSON class User {
String screen_name
String name
...
}
get request Timeline
for “statuses/user_timeline.json”
returns array of Status {
query max_id : String
query screen_name : String
}
datatype Status {
id : String
text : String
favorits : Integer
retweets : Integer
user : User
}
datatype User {
screen_name : String
name : String
...
}

18. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
Metaprogramming xTend – Active Annotations
18
@Request(path="statuses/user_timeline.json",
response=@Response(type=Status, isArray=true))
class Timeline {
String max_id
String screen_name
}
public class Timeline extends AbstractRequest<List<Status>> {
@Override
public List<Status> xResult() {
JSONArray jsonArray = xResponse().getJSONArray("");
List<Status> result = new ArrayList<Status>();
for (int i = 0; i < jsonArray.length(); i++) {
result.add(new Status(jsonArray.getJSONObject(i)));
}
return Collections.unmodifiableList(result);
}
...
xTend compiler + RequestClassProcessor implements
RegisterGlobalsParticipant
TransformationParticipant
CodeGenerationParticipant
ValidationParticipant

19. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
Active Annotations – Simple Examples
19
@AddConstructor
class Customer {
private val String id
@Accessors(PUBLIC_GETTER, PROTECTED_SETTER)
private String name
}
public class Customer {
private final String id;
private String name;
public Customer(final String id) {
super();
this.id = id;
}
public String getName() {
return this.name;
}
protected void setName(final String name) {
this.name = name;
}
}

20. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
Metamodeling vs Metaprogramming
20
xTend Language
xTend Code
e.g. uses annotations to describe
REST request and resource types
xTend Compiler
Code
the desired Java code, e.g. a
REST client library
Active Annotations Class Processors
Code
the desired platform code, e.g.
Code
the desired platform code, e.g.
Code-GeneratorCode-Generator
Metamodel
Model
Code-Generator
Code
the desired platform code, e.g. a
REST client library

21. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
Beyond REST – Active Annotation and Web
21
Endpoints
GWT: Java
Javascript
Cloud Storage
e.g. from Google
HTTP
@GWTJavaScriptObject
@JSONObject
@JavaBean
@CloudStorageEntity
class User {
String screen_name
String name
...
}
object.name = “John”
json.put(“name”, “John”);
bean.setName(“John”);
entity.set(“name”,“John”);
{ name : “John” }

22. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
Beyond REST – Active Annotation and Web
22
class Statuses {
@com.google.endpoints.ApiMethod(
name=“statuses/user_timeline.json”)
@RequestFromEndpoints
@ApiMethodMockup
List<StatusBean> getTimeline(
String screenName,
String maxId) {
...
}
}
@Request(path=“statuses/user_timeline.json”,
response=@Response(type=Status, isArray=true))
class Timeline {
String max_id
String screen_name
}
REST Client Library Request Code
Server CodeMockup Skeleton
a bare bone implementa-
tion for tests
HTTP

23. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
Conclusions
■ Model-driven can be used for Web application
development, especially for REST APIs
■ Active annotations can be used like stereotype
to extend an existing programming language
■ Active annotation are an internal DSL alternative
to custom code-generation
23

24. ECMFA 2016: Metamodeling vs Metaprogramming
Introduction REST Metamodeling Active Annotations Conclusions
Questions
24
xTend Language
xTend Code
e.g. uses annotations to describe
REST request and resource types
xTend Compiler
Code
the desired Java code, e.g. a
REST client library
Active Annotations Class Processors
Code
the desired platform code, e.g.
Code
the desired platform code, e.g.
Code-GeneratorCode-Generator
Metamodel
Model
Code-Generator
Code
the desired platform code, e.g. a
REST client library