Showing posts with label WSDL. Show all posts
Showing posts with label WSDL. Show all posts

Wednesday, September 09, 2015

What is the difference between SOAP and POX on Web Services

My previous two blog talks about two aspects of Web Services. What is the differences between the two methods. To make it simple, it is basically the same except that one is easier and the other is harder. They both return exactly the same result.

Let's talk about the easier one. Using SOAP is by far the easiest way. You just need to compose an array according to the documentation available for the Web Services and send to a function of the WS object.

The harder one is to compose the XML envelop then add the nodes to make a complete XML document and then send it.

How did the Web Services work with two different methods? Actually they are both the same except that the XML is posted to the second stage. Allow me to explain the process.

When we use SOAP, we creates a connection to the Web Services (henceforth WS). We then called the particular function via the connection object and pass it an array of parameters. In PHP the script is as follows.

$client= new SoapClient("http://webservices_address", $opt);
$param=array('action'=>'theaction');
$test=$client->thefunction($param);
echo $test->functionresponse->result;

Now if the arguments is a multiple array type the $param will be something like this

$param=array('action'=>array('subaction'=>subtheaction'))

You have to know what function to call and what parameter to pass. Normally this is found in WS documentations. Now, it is very important to be specific about the object name of the array. It is often case sensitive. "subaction" is not the same as "subAction". Often WS will simply tells you that a parameter is missing because of case differences.

To a user, the PHP script is all that is needed to get it working. In actual fact PHP works in the back ground and actually posts the data in a different form. You guess it right. It actually posts a XML to WS after composing it from the WSDL that it first addressed to. This means that it actually interprets the returned value when it first posts to WS, compose the XML based on the definition then sends the XML to another address (usually a sub address of the original) according to the definition.

Our second method actually composes the XML directly and posts to the sub address. It is therefore the same thing except you need to compose the XML the hard way unless you download the WSDL of the WS and do a transpose yourself.

How does the multiple array looks in XML? It is exactly the same except in different format.

subtheaction

Obviously, the PHP array is much easier to read. Now, you would say why not just use SOAP since it is much easier? Yes it is unless the application you use does not have SOAP functionality. PHP have both SOAP and CURL (which provide POX functionality by sending the XML as post). If I use PHP I would prefer to use SOAP instead of CURL. What if you use an application for your business but that application only have CURL?

Since CURL can post a XML to the WS and still gets back the same result, it is pretty alright to use it to access WS. It will be more difficult as you will need to understand what to do when composing the entire XML. Some WS does provide the XML information and allows POX.

Filemaker is a good application for a small business. It is very easy to create a complete database application without much technical knowledge. To access to WS, there is no choice but to use CURL. It might be harder but it will still work.

Actually Filemaker can post to a web site and gets the result but then it has to call a PHP script, pass the information to it and it in turn calls WS, get the result and return it to Filemaker. It is pretty round the world way but it still works.

Post note. SOAP communication has been discontinued. The only way is to use POX now.




Sunday, August 30, 2015

How to Access Web Services using SOAP

Previously I mentioned about accessing Web Services in Communicating with Apple Web Services. It communicates directly with the Web Services by posting a XML to it.

My previous post talks about using Filemaker to access the Web Services. Actually you can use a browser to access it. In actual fact, using browser is the more common methods of accessing Web Services. Most browser has Javascript facility. Javascript has a function called XMLHttpRequest that can access web services. This method is usually called AJAX (Asynchronous Javascript And XML). Using this method, you still send the XML to the Web Services.

It is no joke composing the XML. There is an easier way to access Web Services if you have a web site that runs on PHP. PHP has a module that provides SOAP (Simple Object Access Protocol). What you need to do is to call the function and pass it an array of the parameters.

Generally you need to tell the Web Services what to do with the data. But how to know what to send? Well, it is quite simple. Web services usually uses a language called WSDL (Web Services Definition Language.) If you use a web browser and call the address directly like a web page, it actually returns you a XML telling you what functionality it has and what parameters to provide.

Below is a simple PHP program to communicate with a Web Services. It calls a function called "thefunction" and passes a parameter called $param. It echoes a node name called "result" in the returned XML.

$opt= array('encoding'=>'UTF-8');
$client= new SoapClient("http://webservices_address", $opt);
$param=array('action'=>'theaction');
$test=$client->thefunction($param);
echo $test->functionresponse->result;

Nested parameters can be done by adding arrays in an array like below

array('higherlevel'=>array('lowerlevel'=>'xxx','lowerlevel2=>'yyy'))

Note that php actually parses the returned xml automatically into an object array. You need to use the object reference method to access individual values. Converting the object to other form is beyond the scope of this blog.

There are some Web Services that require client cert. This can be easily done by adding "'local_cert=>'certname.pem'" to the variable $opt. The cert and key must be in the same file.






Sunday, February 01, 2015

Communicating with Apple Web Services (GSX) via Filemaker

Web services according to WikiPedia is "a method of communication between two electronic devices over a network." There are websites that provide information as a service. Sites like Google Language API which allows you to translate your website directly without you having to create the translation yourself. This means you could translate your web site to hundreds of languages just with the web services code.

In plain language, web services allows you to call a web site from your website by providing a request, or consuming a request ( a most confusing term), with some data. The web site will then provide you with the result. For example, I send a request to Google Language API with "Japanese" as the required language and "How to speak Japanese" as the data. Google Language API will understand your request and responds with the result as "日本語を話す方法". When you change the language to Korean, and use back the same data, the API will respond with "일본어를하는 방법". Isn't that easier than you writing three different pages each with a different language?

Some web sites provide more than just one functionality. You can actually use the service to perform various actions by using it like a "function" with "parameters". In layman language, it means you need to tell the web service what you want to do with the data provided by you. The web services will understand your request and perform the exact action then return you the result. For example, I can go to a plant information web site and do search, update, create, delete, etc. just by calling the same address with different info.

In a web page, we will normally use Javascript to do the calling and showing the response using the technique call AJAX and a newer technique called JSON as data. It has all the functionality available to do it. You just need to compose what to send and get what is returned.

I have the opportunity to write programs using Filemaker (A database program owned by Apple). It has very good interface that allow very easy creation of database interfaces and web pages. However, its scripting facility is a bit lacking. This is especially true when trying to use the technology above to do translation. You practically have to write a code to do the functionality then write the code that make use of the functionality. That is double the work. Luckily there are plug-in that expand the capability of the application.

The following is a description of what I did to call a Web Service from Apple itself using Filemaker. It is a web service provided by Apple to its agents that provide repair services to its customers. The service provides a number of requests with its associated data. For example, if I need to order a spare part, I will call the web services with the request "orderPart" and "xxxxxx" as part number. Apple will then create an entry in its database that records your request and then send the part to you.

The request is send as a XML that contains the "request action" and the data. The response is also a XML that contains the result of the request. In this way user will see the same display yet the transaction is made in the back ground. The Filemaker program will then display the respond data so that user can see the result of the transaction.

Actually it is easier said than done. There is no such functionality available to talk to web services. Filemaker does have a "insert from URL" function that could call a web site and display the result in a field (a place where you can type in a form). However, it only shows the XML returned from Apple directly which is mostly not understood by user. Its XML facility is also not suited for manipulation with XML in this way. Thus the task is to create a code that could call the web services, send the request in XML format and translate the result to user in a readable format.

The very first task is to create the proper XML. Since there is no such function, it has to be created. XML node is generally in the form "<node>value</node>". As you can see, creating it is not a problem. So instead of typing the "node" and the "value" manually, you just need to call the subscript and pass it with the correct parameters.

Problem is that Filemaker (FMP) cannot pass multiple parameters. It does not have arrays too. There is, however, a "List" function that you can use like "list(value1,value2)". Thus you must combine the two information into one by using "list" before passing it as a parameter. You can even create a sort of array by creating a list within a list.

The XML example above is the basic format. XML, like HTML, also can contain properties. It is in the form "<node property='xxxx'>value</node>". Obviously these nodes can be nested. Setting the property nodes aside (as it is normally not used in "body"). There are four ways to create the XML.

1. The beginning node ("<node>"). With this and the ending node, you can create a nested node to what ever level you want.
2. The ending node ("</node>")
3. The complete node with value ("<node>value</node>").
4. The NULL node ("<node/>")

It is very easy to take the first parameter and treat it as a node by enclosing it with "<" and ">". The value is placed next then the first parameter is used again by enclosing it with "<" and ">
".

For those that only need the node name like 1,2, 4 above. It is constructed accordingly.

The value must not contain characters used by XML itself like "<" and ">". Therefore all the values have to be filtered or modified to ensure that the value does not end up as the XML itself. This is called "escaping". With this we are able to construct any XML body. This script will then be store as a script by itself. It always write to a global variable like $$xml so that it does not even need to return a value. The script then becomes a function that create xml nodes.

How then should we add headers. It is very simple. Since we always access to the same address, the header seldom changes. Why not just store it as a plain variable? This is exactly what I did.

In another script we will assemble the xml step by step. Fist we store the header into the variable $$xml. Then we use "run script" to run the script that creates the xml by passing the appropriate values beginning with a code that define what type of nodes we are creating. Repeat the subscript till the whole xml is complete. The result is then a well formed xml. You could even test the output by storing the $$xml in a field or just a custom dialog to ensure that the xml is correctly form by copying and pasting the result in a xml editor.

With the xml available, the next task is to send it to the Apple web services (GSX). Luckily, this functionality is available as a plug-in. BaseElements has the plug-in that could do a post to a website and get a respond into a variable instead of a input field. This functionality is exactly what we need to talk to the server.

The last part is to get the result out of the xml. This functionality is again not available. However, BaseElements does have the functionality to extract values from the xml. It may not be the functionality that I am looking at but at least it can be done. The best way is to transform the whole response xml into something  that is humanly manageable like an array without having to write long codes to do it. But then with the limitations, it is still better than nothing.

The conclusion is that Filemaker can talk to web services. With the database capability, getting chunks data out of the web services is a possibility.

MBS has an excellent example of communicating with GSX. MBS Blog.

Apple will be changing the format used for sending and receiving data.  Please go to part 2 to see how it could be done.