Hello and welcome to Web Services in the OutSystems platform. A web service
is a set of functionalities offered by a software system over the world wide web.
So web services provide a way to do remote procedure calls over the internet,
allowing completely disparate systems to provide functionalities to other systems.
The great thing about web service producers and consumers is that they can
run over completely different technologies and actually exist halfway
around the world from each other. Now, there's two kinds of flavors to web
services: SOAP and REST.
Both of them are supported in the OutSystems platform. SOAP stands for Simple
Object Access Protocol and the main characteristic of SOAP web services is
that they formalize the API they provide in a Web Services Description Language
file also known as WSDL. In this contract file, all of the services'
methods and parameter types are described, allowing the consumer to
import it to generate the calling interface on its own side, as well as to
validate all of the communications during runtime. REST takes a fairly
different approach. REST services do not have a formal API contract file that the
consumer can just parse to generate the calling API. Rather it tends to privilege
a more freeform approach in the interest of improved performance. So, to make up
for this lack of contract, REST service providers tend to provide a
human-readable documentation that helps consumers know what's available in the
service.
Furthermore, unlike SOAP, calls to REST methods can be done over several HTTP
methods that reinforce the nature of the operation that you're executing. So for
example you may have a GET method call to retrieve information, a POST to insert
information or a PATCH, that is a less known HTTP method, to update a record.
The payload of REST messages,
the body of these messages, is usually compact JSON but some REST web services
employ XML as well. Let's look now at how you can consume and expose web
services of both kinds in the OutSystems platform. Consuming SOAP web
services is very simple. Just go to the Logic tab and in the SOAP node
select Consume SOAP Web Service. After you do this, you just need to specify the
URL that points to the contract file and when you press OK, Service Studio will
automatically create for you all of the methods and the supporting structures
that it finds in the contract file. After these elements are present in your
module they can be used normally as if they were actions of your module or
structures of your module. It's important to note that while you cannot alter, for
example, the parameters in these methods or the attributes of the structures that
come in the web service, it is possible to adjust by what name and description
these elements are known, the default values for these elements and if the web
service has got integrated authentication and SSL. The process of
exposing a SOAP web service is very, very similar. In the Logic tab again you can
select to expose the web service, then for each method that you will want to
export you can create it on the web service node and then it's just a matter
of writing the code of these methods as you would do on any other action in your
module. It's important to note that you do not have to worry about managing the
WSDL file. That's actually taken care for you by the OutSystems platform. And
over here you can see the location of these important files for your web
service. Due to its nature, consuming REST is a bit more complex than SOAP. Very
similarly, you go to the Logic tab and on the REST node you select Consume REST
API. If you then select to add a single method you will need to specify what is
the URL where that method, individual method, responds to
as well as the HTTP method that should be used for this communication, as you
can see in the screenshot. Now, since there is no contract for the OutSystems
platform (or indeed any platform) to know what is the calling convention of the
REST method, you need to provide it with a sample of the response that this
method returns. Using the sample the platform can infer what parameters exist
and what types they are so that it can create the proper API, namely structures
that might be needed.
Probably the simplest way to do so, is to test the call to this method, therefore
receiving a response. If you do this you can opt to copy the response that you
just got to the body tab and press OK so that it can generate the API. Having said
that, if you have access to an explicit documentation provided by the owners of
the web service, you better use the sample body that they provide in the
documentation, instead of the test result. Very much like in SOAP, once the
methods and the structures exist you can freely use them in your module as you
would use other actions and structures. Unlike SOAP however, seeing as the
format of REST calls is very loose, it is actually possible for you to go
there and adjust a lot more things. So for example if you know that there is an
output parameter that the sample body that you provided doesn't show, you can
actually right click and add this output parameter. Likewise, you can change the
types or add attributes to the structures that were introspected. And a
great thing that REST in the OutSystems platform provides, that goes beyond SOAP
is that it allows you to write callback functions. So, for example, you can trap
the before request and the after response of any call to a REST method.
You will normally use these callbacks to, for example, prepare the request before
it goes out or to adjust any returned values so that they arrive to your
application in a
format that's more controlled. Now if consuming REST is a little bit more
convoluted than SOAP, exposing is exactly the same way. So you just go into the
Logic tab, you select Expose REST API, thus creating the REST service. Then you can
add the methods that you see fit
also specifying any inputs or output parameters that it may have and then you
just write the code of your rest methods as you would write any action.
It's important to note that the platform provides true enterprise-grade support
for the runtime of your services,
so for example if you go to Service Center and you go into the page
of your module, in the Integration tab you can see information about all sorts
of web services, both consumed and exposed, that this module has. Likewise, in
Service Center, if you go into the Monitoring tab and in the Integration
sub-tab, you'll be able to see all the events of interactions with web services
and therefore check how long these calls are taking and if there's any failures
on any of these calls. And that's SOAP and REST web services in a nutshell on
the OutSystems platform.
This is an incredibly powerful feature and we hope this will be very handy in
your developments.