EMF-REST generates a web application which is called as your Eclipse project. Inside the application, a servlet mapping called app is created which interprets the rest of the URL. For instance, in our example the project is called Demo so the application will have the prefix http://<server>/Demo/app/....
The servlet takes the URL to navigate through the models and their elements. Thus, the next element in the URL is the name of the model (e.g., Family in our example, i.e., http://<server>/Demo/app/<Family>). Once the model name has been indicated, you can ask for a particular model, e.g., the Simpsons family by adding at the end of the call (e.g,. http://<server>/Demo/app/Family/Simpsons). This last URL can be seen as the entrypoint for your particular family model and will return the data of the root element.
Once you know how to access to the root of your model, you can navigate through your model using the reference names. For instance, the concept Family has the reference sons so we can call http://<server>/Demo/app/Family/Simpsons/sons to get the list of sons of the Simpsons family. Other example would be http://<server>/Demo/app/Family/Simpsons/parents, which returns the set of parents of the Simpsons family.
If you want to access to a particular element contained in a reference you can use the identifier of the element. By default, EMF-REST look for an attributes called id, name or has the unique attribute activated, although this behaviour can be changed in the generated code (see How elements are identified for more info). For instance, the call http://<server>/Demo/app/Family/Simpsons/daughters/Lisa will return only the element representing Lisa.
Your REST API calls can include the parameter index to specify the index of the element you want to access in a list. The two following URLs will show exactly the same element in the Simpsons family example:
http://<server>/Demo/app/Family/Simpsons/daughters?index=0
http://<server>/Demo/app/Family/Simpsons/daughters/Lisa
By default, EMF-REST look for an attributes called id, name or has the unique attribute activated to identify an object. However, sometimes this is not the correct behavior and special cases can appear. To specify how a model element is identified you have to modify the class webmapi.service.IdentificationResolver, where you will find the methods in charge of finding elements by their id.
The elements of your model are automatically translated into a JSON object. A model elements is therefore represented by a JSON object which includes a set of name/value pairs representing its attributes/references. Attributes are represented as primitive-typed name/value pairs where as references are translated into a name/value pair where the value is an array of objects.
One important point is the inheritance, when a reference has inheritance a JSON object is generated. This object will have one attribute for each class that inherit from the reference type.
For instance in the Simpsons example the "pets" relation could be a Dog, Cat, RaceDog or HuntingDog. Here you can see an example of the generated JSON in this case:
"pets":{
"racedog":{
"breed":"Greyhound",
"name":"Santa's Little Helper"
},
"cat":{
"breed":"Unknown",
"name":"Snowball II"
}
}
The same as JSON, the document is translated to an XML object with the same content of the the JSON document but in XML structure
The following example shows the same element in JSON and XML format
{
"family":{
"address":"742 Evergreen Terrace",
"daughters":{
"daughter":[
{
"firstName":"Lisa",
"lastName":"Simpson",
"family":{
"address":"742 Evergreen Terrace"
}
},
{
"firstName":"Maggie",
"lastName":"Simpson",
"family":{
"address":"742 Evergreen Terrace"
}
}
]
},
"parents":{
"parent":[
{
"firstName":"Homder",
"lastName":"Simpson",
"family":{
"address":"742 Evergreen Terrace"
}
},
{
"firstName":"Marge",
"lastName":"Bouvier",
"family":{
"address":"742 Evergreen Terrace"
}
}
]
},
"pets":{
"racedog":{
"breed":"Greyhound",
"name":"Santa's Little Helper"
},
"cat":{
"breed":"Unknown",
"name":"Snowball II"
}
},
"sons":{
"son":{
"firstName":"Bart",
"lastName":"Simpson",
"family":{
"address":"742 Evergreen Terrace"
}
}
}
}
}
<?xml version="1.0" encoding="UTF-8"?>
<family>
<address>742 Evergreen Terrace</address>
<daughters>
<daughter>
<firstName>Lisa</firstName>
<lastName>Simpson</lastName>
<family>
<address>742 Evergreen Terrace</address>
</family>
</daughter>
<daughter>
<firstName>Maggie</firstName>
<lastName>Simpson</lastName>
<family>
<address>742 Evergreen Terrace</address>
</family>
</daughter>
</daughters>
<parents>
<parent>
<firstName>Homder</firstName>
<lastName>Simpson</lastName>
<family>
<address>742 Evergreen Terrace</address>
</family>
</parent>
<parent>
<firstName>Marge</firstName>
<lastName>Bouvier</lastName>
<family>
<address>742 Evergreen Terrace</address>
</family>
</parent>
</parents>
<pets>
<racedog>
<breed>Greyhound</breed>
<name>Santa's Little Helper</name>
</racedog>
<cat>
<breed>Unknown</breed>
<name>Snowball II</name>
</cat>
</pets>
<sons>
<son>
<firstName>Bart</firstName>
<lastName>Simpson</lastName>
<family>
<address>742 Evergreen Terrace</address>
</family>
</son>
</sons>
</family>
The javascript generated by EMF-REST is located in the folder scripts of your folder WebContent. The file is called api.js and defines a set of helper functions which helps you to do all the work to interact with the API.
RestAPI variable is always generated from which you can make REST calls to your API. You can use the following functions:
callGet(url, doneCallBack, depth, failCallBack)callPut(url, data, doneCallBack, depth, failCallBack)callPost(url, data, doneCallBack, depth, failCallBack)callDelete(url, doneCallBack, depth, failCallBack)A function is generated for each element in your model. This function has two parameters:
baseUrl, which defines the base url of the objectpId, which defines the id of the objectBecause nobody is perfect, for sure we have forgotten to document something that it is important to you for undestand how EMF-REST works. No problem, just contact us.