Prerequisites
In order to understand the content of this lesson, make sure you watched the following lesson:
Introduction
Usually, Web applications do not exist standalone but need to integrate with external systems and applications that are on the company intranet. The best way to make different applications communicate with one another is by using a Web Service infrastructure. That’s why it is important to know how you can easily define your Web Services using WebRatio Platform. This lesson gives you the basic knowledge you need to understand how you can publish a Web Service with WebRatio Platform. Other lessons that follow will explain how to model a SOAP and a RestFul Web Service. This lesson does NOT cover how to invoke Web Services.
Web Service Overview
The W3C defines a Web Service as a software system designed to support interoperable machine-to-machine interaction over a network.
A Web Service has an interface described in a machine-processable format (specifically WSDL). Other systems interact with the Web Service in a manner prescribed by its description, typically conveyed using "HTTP", a conjunction of different Web-related standards.
Web Service Structure
Web Services are application components that communicate using open protocols; they are self-contained, self-describing, and can be used by other applications. Web Services have a service descriptor file that distinguishes their methods from the structure of the messages they exchange. The service requestor can use this information to interact with a specific "Web Service Provider".
You can think of an individual Web Service as a piece of software that performs a specific task (also known as a function), and makes that task available by exposing a set of operations that can be performed (known as methods or "Web Methods") with the task.
Additionally, each of the methods exposes a set of variables that can accept data passed into the method. These variables are known as parameters or properties. Together, the properties and methods refer to a Web Service's interface.
Web Service Structure Example
For example, "Company A" creates a Web Service that provides currency rate functionality, which may expose a method called "GetRate". "Company B" is then able to pass a parameter, called "CountryCode", into the "GetRate" method. The "GetRate" method takes the "CountryCode" parameter, looks up the appropriate currency rate in a database, and returns the rate back to the program that requested it.
In this example, which database did "Company A" use to access the currency rate information? What was the name of the database server? What communication mechanisms and security mechanisms were used to access the database server? The answer to all of these questions is, "It doesn't matter."
The beauty of a Web Service is the concept of encapsulation. Encapsulation allows the complexity of retrieving the actual currency rate to be completely self-contained within the company that created the Web Service, "Company A". The only thing that "Company B" knows is that they called a Web Service to get a currency rate and it was given to them.
Web Services are made possible by placing the programs, or applications, on a "Web Server". Since the application resides on a Web Server, it can be called, or invoked, from any other computer on the network by using "HTTP". The Web Service provides seamless distributes computing across the entire network, as long as both sides know how to use a Web Service.
Expose a Web Service
A Web Service must be exposed in order to be available from other Web applications and to comply with the W3C specification. Exposing a Web Service means that a programmer creates the interface for it.
There are mainly two ways to expose a Web Service:
"SOAP" is a communication protocol defining the message format to be used for communication with Web Services. "SOAP" is based on "XML" and is a W3C standard.
"RESTful" is an architectural style that specifies constraints that, if applied to a Web Service, include desirable properties such as performance, scalability, and modifiability, which 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".
Service View Overview
Service View
Web Services must be modeled in a dedicated view of the project, which is the "Service View".
A "Service View" is a container of Web Services and scheduled operations models made available by the application. You can have several "Service Views" in the same Web Project. Each "Service View" is considered a Web Service containing different methods and is represented as a new tab in the Web Project.
How to Add a Service View
Let’s suppose you want to model a Web Service that allows you to search for employees. In order to model this Web Service, let’s continue working on our "CRM" web project. In this project, there is the Domain Model containing the "Employee" entity.
To add a "Service View" to your project, open the "Project" tab. In the main work area, right click on the "Service Views" icon, and choose the "Add Service View" command. The best practice is to give a meaningful name to each object in your project to make it easier to recall the element’s purpose, such as "EmployeesWebServices" (with no spaces within it). Press the "Finish" button to confirm.
Port
A Web Service may have different "Ports".
A "Port" is a Container of Web Service operations. It defines an individual end point by specifying a single address for binding. You can have several ports in the same "Service View".
The name of the "Port" will be used as port name in the WSDL definition if the Web Service is exposed using "SOAP", or as port name in the WADL definition if the Web Service is exposed using "REST".
The "Port" is mandatory.
How to Add a Port
To add a "Port", select the "Port" icon from the "Container" section of the toolbar and click in the work area. Give it a meaningful name, such as "SearchForEmployees" (with no spaces in it). Every time you place a "Port" in a "Service View", the "Solicit" Operation is automatically added by default.
In a "Port", you can add more then one "Solicit" Operation by selecting the "Solicit" icon from the "Service Components" section of the toolbar and click inside the "Port".
Web Service Skeleton
Once you have a "Service View" and at least one "Port", you can start modeling your first Web Service. Let’s suppose you want to expose a Web Service that contains a method letting the service requestor search for employees. The method receives the values provided as search criteria and gives back the list of employees matching the criteria. This is how the model of the Web Service method appears.
All Web Service methods can be modeled using the same skeleton. There is an entry point, which is the "Solicit" operation, and two exit points, one for success and the other for error. The success exit point is modeled with a "Response" operation and the error exit point is modeled with an "Error Response" operation. Between the entry point and the exit point is the business logic that calculates the Web Service response. Here you can use any operation provided by WebRatio Platform. Let’s see in detail how each dedicated Web Service operation works.
Solicit Operation
The "Solicit" operation is the entry point of the Web Service method. Its name is the name of the method. It defines the structure of the Web Service request for the specific method.
This operation has several properties:
- "Invocation Style". The "Invocation Style" property let you choose whether you want to expose the Web Service method using SOAP XML or REST. The choice affects also the structure of the request.
- "Stateful". The "Stateful" property enables the session usage in the Web Service. This means that you can use volatile entities in the operation chain. This property can be used only when the "Invocation Style" is set to REST. In fact, when using SOAP, you do not have a user session.
- "Protected". The "Protected" property activates user authentication on the Web Service.
If you choose the "REST" option as "Invocation Style", two other properties are available:
- "Request Method". The "Request Method" property lets you choose whether you want to expose the REST Web Service using the "GET"," POST", "PUT" or "DELETE" method.
- "Content Type". The "Content Type" property let you choose whether you want to use the XML or JSON request type as the structure.
The "Solicit" operation can also be configured by creating the request message that calls the Web Service correctly.
Response Operation
The "Response" operation is the Exit Point of the Web Service method used when the business logic contained in the method is executed properly. It defines the structure of the XML or JSON response for the method.
The "Response" operation can also be configured by creating the desired response message.
Error Response Operation
The "Error Response" operation is the Exit Point of the Web Service method used when the business logic contained in the method fails. It defines the structure of the XML or JSON response for the method, in case of exceptions.
The "Error Response" operation can also be configured by creating the desired response message.
Create Messages on Solicit, Response and Error Response Operation
"Solicit", "Response" and "Error Response" operations share the way in which the message is modeled on the operation itself.
You can use different elements to create the message structure.
- "Body Parameters"
- "Simple Fragments"
- "Complex Fragments"
- "Query String Parameters"
Only for the REST request, it’s possible to use the "Query String Parameters".
You can learn more about the creation messages in the following lessons depending on the Web Service that you want to expose, SOAP or REST: "Exposing a Web Service - SOAP" online lesson or "Exposing a Web Service - REST" online lesson.