Prerequisites
In order to understand the content of this lesson, make sure you watched the following lesson:
Introduction
Usually Web applications are not standalone; they need to integrate with external systems and other Applications in the company intranet. The best way to make different applications communicate with one another is to use a Web Service infrastructure. That’s why it is important to know how you can easily define your Web Services using WebRatio Platform.
In a previous lesson you already gained the basic knowledge about how to publish a Web Service.
This lesson gives you the basic knowledge to help you publish a RESTful Web Service. A separate lesson explains how you can publish a SOAP Web Service. This lesson does NOT cover how to invoke Web Services.
REST and WADL Overview
"RESTful" is an architectural style that specifies constraints that, if applied to a Web Service, include desirable properties such as performance, scalability, and modifiability, that enable services to work best on the Web. The "REST" architecture works with a client/server architecture and is designed to use a stateless communication protocol, typically "HTTP". This type of Web Service can be modeled using XML or JSON format. In the example shown in this lesson, the request and the response of the Web Service will be of the JSON type.
WebRatio Platform introduced WADL generation for all modeled REST Web Services in the same manner as for WSDL generation for SOAP Web Services.
"WADL" means "Web Application Description Language". The official website http://www.w3.org/Submission/wadl/ describes the WADL as follows:
"An increasing number of Web-based enterprises (Google, Yahoo, Amazon, Flickr to name but a few) are developing HTTP-based applications that provide programmatic access to their internal data. Typically these applications are described using textual documentation that is sometimes supplemented with more formal specifications such as XML schema for XML-based data formats. WADL is designed to provide a machine processable description of such HTTP-based Web Applications."
The URL for the page where you can find the generated WADL Definition is: http://<host>:<port>/<application-name>/wadl.do You can see in the following image an example of the generated WADL.
REST Web Service - The Model
In a previous lesson you learned how to model the skeleton of a Web Service. Once you have a "Service View" and at least a "Port", you can start modeling your first REST Web Service. Let’s suppose you want to expose a REST Web Service that contains a method for letting the service requestor search for employees. The method receives the keyword provided as search criteria and gives back the list of employees matching the criteria. This is how the model of the REST Web Service Method looks.
As you can see, there is an "entry point", which is the "Solicit" operation, and two exit points, one for success and the other for error. Since we are creating a REST Web Service, it is necessary to set the "Request Method" and the "Content Type" properties on the "Solicit" component.
The "Request Method" property lets you choose whether to use "GET", "POST", "PUT" or "DELETE" methods. Each method is used for a specific case.
- "GET". If you use this method, you can retrieve the information about an object. For example, when you make a research on the employees of a company.
- "PUT". If you use this method, you can modify the information of an object's instance. If the object doesn't exist, the method creates it.
- "POST". If you use this method, you can create a new instance of an object.
- "DELETE". If you use this method, you can delete the instance of an object.
After choosing the method, you need to set the "Content Type" property. A REST Web Service can be called by using the XML or JSON format, depending on the request type.
For this example we chose to use the "GET" method. The "Content Type" property is disabled in this case, because for this method only the JSON format is available. Also for the "Response" component, we need to specify the "Content Type" property, depending on the response that you want to structure, in XML or JSON format. For this example, that property is set to JSON value. Let’s see how you can create the REST Message.
REST Message Overview
"Solicit", "Response" and "Error Response" operations share the way in which the message is modeled on the operation itself.
To create the message structure, you can use the following objects:
- "Body Parameters"
- "Simple Fragments"
- "Complex Fragments"
- "Query String Parameters"
Body Parameters
"Body Parameters" must be used to create the message structure. They can be used standalone to obtain a simple structure; for example, to create feedback for an operation result. In addition, on each parameter you can set the "XSD Provider" and the "XSD Type". On the "Solicit" Operation it’s possible to use a "Body Parameters" only for a REST request with "POST" and "PUT" methods.
The example can be to search for employees by keyword, having the "keyword" as "Body Parameter". See the examples. In the Properties View of the "Body Parameter", you can define the type depending on whether the element is a simple type, for example a string, or an element based on XSD. To define the type, you can use the "XSD Provider" and the "XSD Type/Element" properties. Other properties present in the Properties View relate to the definition of the cardinalities: "Min Card." property and "Max Card." property. If the "Min Card." property is set to "0", this "Body Parameter" is optional. By default this property is set to "1". If the "Max Card." property is set to "-1", this "Body Parameter" has unbounded max cardinality. By default this property is set to "1" value.
Simple Fragments
"Simple Fragments" can be appended to a "Body Parameter" in order to declare a two-level structure of the message. Let’s suppose you want to create a request for searching for employees, grouping all criteria into a specific node. On the "Solicit" operation it’s possible to use a "Simple Fragments" for a REST Request with "POST" and "PUT" methods.
See the examples. In the Properties View of the "Simple Fragment", you can define his type depending on whether the element is a simple type, for example a string, or an element based on XSD. To define the type, you can use the "XSD Provider" and the "XSD Type/Element" properties. Other properties present in the Properties View relate to the definition of the cardinalities: "Min Card." property and "Max Card." property. If the "Min Card." property is set to "0", this "Simple Fragment" is optional. By default this property is set to "1". If the "Max Card." property is set to "-1", this "Simple Fragment" has unbounded max cardinality. By default this property is set to "1".
Complex Fragments
"Complex Fragments" can be appended to a "Body Parameter" in order to declare a multi-level structure for the message (e.g., create a list of employees who have a predefined set of Attributes). You can add Simple Fragments or use an XSD Definition to define the fragment structure. On the "Solicit" operation it’s possible to use a "Complex Fragments" for a REST request with "POST" and "PUT" methods.
See the examples. In the Properties View of the "Complex Fragment", you can define its type depending on whether the element is a simple type, for example a string, or an element based on the XSD. To define the type, you can use the "XSD Provider" and the "XSD Type/Element" properties. Other properties present in the Properties View relate to the definition of the cardinalities: "Min Card." property and "Max Card." property. If the "Min Card." property is set to "0", this "Complex Fragment" is optional. By default this property is set to "1". If the "Max Card." property is set to "-1", this "Complex Fragment" has unbounded max cardinality. By default this property is set to "1".
Query String Parameters
"Query String Parameters" are the part of the URL used to pass data as input to a Web Service. The set of the "Query String Parameters", added on the "Solicit" operation, composes the final "Query String" to use in the URL. The "Query String" is composed of a series of field-value pairs. Within each pair, the field name and value are separated by an equal sign, "=". The series of pairs is separated by the ampersand, "&".
Query strings can be used standalone to obtain a simple structure; for example, to create feedback for an operation result. In addition, on each parameter you can set the "XSD Provider" and the "XSD Type".
REST Message
The Request Message that we want to obtain for our example, through the "Solicit" component with the "GET" method, is to use a one parameter as "keyword" to search, by adding a "Query String Parameter".
In order to obtain this result, we need to define the structure of the "Response" message. Since we want to return a list of employees having a predefined set of attributes, we can define a "Complex Fragments" in order to declare a multi-level structure for the message. In this way we can accept, as the result, a list of elements having type= employee.
How to Create a REST Web Service
Let’s see how to model the search for employees by keyword Web Service. For this example, we will continue working with our "CRM" web project. We have already created in the "EmployeesWebServices" service view the "SearchForEmployees" port with a "Solicit" component . We have also the Domain Model containing the "Employee" object.
We start by configuring the "Solicit" operation. Double-click on it and enter a meaningful name. Move to the Property View and set the "Invocation Style" to the "REST" value. Then choose for the "Request Method" property the "GET" value.
Let’s create the Request Message by adding only one "Query String Parameter" because in this case we have a unique search criteria. Right-click on the "SearchByKeyword " Solicit Operation and choose the "Add" and then the "Query String Parameter" option. Give a name for the parameter, such as "keyword". In the Properties View, press the "Edit" button next to the "XSD Simple Type" property, choose the "string" type and press the "OK" button.
To retrieve the employee matching the search criteria, let’s use a "Selector" component based on the "Employee" Entity.
Let’s suppose that the employees matching the "keyword" are those containing the keyword in the "First Name", "Last Name" or "Email". To model this requirement we need to add, to the "Selector" component, a "Conditional Expression" composed of three different "Attribute Conditions", one for each attribute we want to check. Finally, set the "Required" property as "False".
This procedure must be repeated for the other two attributes that we have chosen to filter: "Last Name" and "Email".
Since we want an employee to be listed in the results if the keyword is contained in at least one of the Attributes, we have to change the Operator combining the Conditions, which is the "And" Operator by default. Move to the "Properties View" of the "Conditional Expression" and change the "Boolean Operator" property to "Or".
In order to provide the search criteria to the "Selector Component", let's use an "OK Flow" connecting the "Solicit" operation and the "Selector" component. Double-click on it, uncheck the "Enable Default Binding" property and then bind the "keyword" query string parameter with each "Attribute Condition". Finally, press the "OK" button to confirm.
Once the results are retrieved, we need to configure the Response Message. This "REST Web Service" sends back a JSON, so we need a "JSON I/O" component to create a JSON Document containing all the results. This Component works with Entities mapped on XSD, so we need to associate the "Employee" object in the Domain Model of the project with the XSD.
The reference of the "XSD Provider" has already been added to the project. To see how to add an "XSD Provider", refer to the "Invoking SOAP Web Service" online lesson.
To associate the XSD to the entity, select the "Employee" object and move to the "XSD" tab in the "Properties View". Let's now associate the object with the "XSD Provider". Press the "Select" button next to the "XSD Provider" property, select the "XSD Provider" of your choice and press the "OK" button. Now, associate the "XSD Type" of the "XSD Provider" as soon as you have chosen it. Press the "Edit" button next the "XSD Type" and choose the "employee" type, then press the "OK" button. In this way, the "Employee" Object is associated with the structure of the XSD.
Now, you can connect the Attributes to the XSD. Select the "oid" attribute in the "Employee" object. For the "XSD Element" property choose the corresponding XSD element of the attribute, in this case "employeeId". This procedure must be repeated for the other attributes of the Object.
Now, back to "EmployeesWebServices" service view. Select the "JSON I/O" component from the toolbar section related to "Service Components" and place it in the Port. In the Properties View of the component, set the "Mode" property to "Export"; in this way the operation creates a JSON Document using the retrieved information. Press the "Select" button next to the "Entity" property and, in the opening dialog, select the "Employee" object.
Let's now add the "Parameter Binding" to pass the Employee Primary Key to the "Condition". Add an "OK Flow" connecting the "Selector Component" and the "JSON I/O" component. Double-click on it. As you can see, since the two components are based on the same Entity, WebRatio Platform automatically infers this "Binding".
Let’s now create the Web Service Response. Select the "Response" item from the "Service Components" section of the toolbar and click inside the Port. Right-click on the "SearchByKeywordResponse" response and select the "Add" and then the "Body Parameter" option. Type a name for it, such as "employeesList". The cardinalities for the "Body Parameter" are not modified, remaining with a value of "1" for both properties. Since we are going to pass an entire JSON Document to the "Response" operation, let’s add to the "Body Parameter" a "Complex Fragment" element. Right-click on the "employeesList" body parameter from the Outline View, choose the "Add" and then the "ComplexFragment" option. Give a name to it, such as "employee". Move to the Properties View. Press the "Select" button next the "XSD Provider" property and choose the "XSD Provider" that you have in the project. Now choose the "XSD Type" property to which the "Complex Fragment" refers. Press the "Edit" button next to the "XSD Type/Element" property and choose the "employee" type. Then press the "OK" button. Now change the cardinality of the result. Set the "Min Card." property as "0" because you might not get results and set the "Max Card." property as "-1" because you may have more than one result.
To provide the JSON Document created by the "JSON I/O" operation to the "Response" operation, let's use an "OK Flow" connecting the "JSON I/O" component and the "Response" component. Double-click on it and bind the "Employee JSON Documents(s)" with the "employeesList/employee[array]".
Now let’s consider the case in which the Web Service call fails for some reason. Select the "Error Response" item from the "Service Components" section of the toolbar and click inside the Port. Before adding the "KO Flow" to handle the failure case, let’s enclose all the operation chain in an "Operation Group". Now, add a "KO Flow" that connects the "Operation Group" and the "Error Response". Double-click on it to and write an error message as input for the "Fault Message".
Expose a REST Web Service
How to Enable the REST Summary Page
To see if the Web Service is up and running, it’s possible to generate a dedicated section containing the REST Web Service Documentation. Open the "Project" tab. Move to the Properties View and select the "Services/Jobs" tab, and then check the "Enable REST Summary Page" property. In this way you can access a page showing a sample request and a sample response for each REST Web Service Method.
REST Summary Page Structure
When you publish the REST Web Service by generating the Web application in the browser, open the page "http://localhost:8080/CRM/RestSummary.do" where all information about the REST Web Service is displayed. The call is displayed in two sections: "Request" and "Response".
You can add the notes by selecting the "keyword" query string parameter in the Outline View. Move to the Properties View and select the "Comment" tab. Then you can write a note that explains, for example, the function of this "Query String Parameter".
Test a REST Web Service
To test the Web Service you can use the example of the URL in the "Request" section. The URL is composed of the path to access the REST Web Service, followed by "?" and then the "Query String Parameters" equal to the input values.
How to Test a REST Web Service
Now let's publish a Web Service, and "Generate and Run" the current status of the Web application to test it.
As soon as the browser opens, you can see the call of the Port in the "RestSummary" page. In this case, we see the "SearchForEmployees" Port and then the structure of the "SearchByKeyword" solicit operation.
Select the first URL shown in the "Request" section, and then copy and paste it into the browser. Now that it is queued, we must add the "keyword" parameter to the URL followed by the value that you want to search, for example "keyword=John". You can see the response of the search employee by the REST Web Service.
- "URL" that must be used to invoke the Web Service.
- "Input Parameters" added to the parameters list for the "Solicit" operation on its type, and notes (if any).
- "Example", which is the relative example of the URL.
- "Output Parameters", which is the parameters list that is the result of the Web Service Response and notes (if any).
- "Example" is the structure of a final example of the result of the call.