JSON Web Services
DataFlex Web Services support returning JSON in addition to the standard SOAP/XML data format. JSON is a lightweight data interchange format, and you can find out more about the actual data format on json.org. JSON is primarily used together with Ajax applications, particularly with JavaScript, where SOAP/XML can be more complicated and difficult to use.
JSON vs. SOAP/XML
JSON Web Services is a bit of a misnomer, as it merely refers to the data format exchanged over the web. The data format is completely transparent from a DataFlex point of view. A Web Service method in a DataFlex web application is just a published method, with standard parameter types and return types (String, Integer, Date, etc.). The built-in Web Services layer in DataFlex and WebApp Server takes care of the data format/protocol, whether it's SOAP, JSON, plain XML, or pure HTTP query strings, and transforms the data between the specific format/protocol and proper DataFlex parameter and return values.
This means that as a publisher of a web service, you don't necessarily have to choose between exposing a web service method via SOAP or JSON. The choice of whether to use SOAP or JSON to call your web service lies with the client. A web service method can be invoked with any of the supported protocols and data formats. You can even have multiple clients using different data formats and protocols to invoke the same web service method. The server sorts it all out, and by the time it gets to your DataFlex code, you don't even necessarily know the data format/protocol used in the data exchange.
If the client side has proper support for SOAP/XML, such as DataFlex, Java, or .NET, SOAP is usually the preferred data exchange protocol. Most mature development platforms have support for WSDL, so you can point them to your Web Service URL, and they can automatically discover your exposed web services, parameter types, etc. This is typically a much easier and more convenient way to interface with your web services.
However, if the client is in a more constrained and limited environment, such as a browser, JSON is typically the preferred way to interface with your web services.
Using DataFlex Web Services from a Browser with AJAX and JSON
JavaScript in a web browser is the primary intended use of JSON. While working with web services with JSON is seemingly a little more low-level than using SOAP, it's quicker and easier to use in a browser environment than SOAP.
To request that a web service returns data in JSON format instead of SOAP/XML, you simply append /JSON to the web service method URL. For example:
http://localhost/TestService.wso/SayHello/JSON
The trailing /JSON in the URL tells the web service that you want data returned in JSON format.
Accessing the .wso in a browser and following the link for the specified web service method also demonstrates how to invoke the web service so it returns data in JSON format. You can even test the service in the browser and see the returned data in JSON format. This is very useful to let the test page automatically construct your URL as you're testing the service, and then when you know your call works as it should, just copy the URL with parameters and all into your JavaScript code.
You can use both GET or POST when invoking the web service, although GET is typically much easier to use and debug, and therefore usually the preferred method. The parameters should be supplied either as part of the query string or as part of the post data, in standard application/x-www-form-urlencoded form. For example:
http://localhost/TestService.wso/SayHello/JSON?sName=Jason
If you omit the trailing /JSON part of the URL, the data will be returned in plain XML instead of JSON format. Plain XML format is similar to SOAP but without the SOAP envelope and body wrapper, containing just the raw return value in conforming XML format.
Note that only the data returned from the web service is in JSON format. Parameters are still specified in the simple and easy-to-use standard application/x-www-form-urlencoded form, typically as a simple query string.
Supported Data Types with JSON
In general, web services returning JSON support the same return types as outlined in the section Supported Data-types in Server Web Services.
However, while all types, especially struct/array, can be returned from a web service method in JSON format, only the data types listed in the Fundamental data types section can be used for parameters. In particular, struct/array types cannot be used as input parameters, while they can still be used as output/return types. Byref parameters cannot be used with JSON and are treated as by-value. XMLHandle is typically of limited use as a return type with JSON and is returned as a string.
Recommendations when Writing Web Services to be used with AJAX/JSON
While it's true that you typically don't have to worry about whether the web service method will be used with JSON or SOAP, there are some things worth considering that can make a significant difference when using the web service with JSON.
SOAP is often used in more formal scenarios, where you may not always know the other party calling your web service. Well-adopted standards such as XML schemas, SOAP, and WSDL ensure that your users can use your service with great interoperability, even with complex web services that use nested structured parameter and return types.
JSON is often used in more informal scenarios, where the other party calling your web service is, more often than not, yourself or someone on your team. In these scenarios, the web service is usually a private interface part of a larger web application and is used together with Ajax.
It's in this role as a less formal interface, part of a larger application that JSON really shines, and much of the complexity surrounding the formality of SOAP is usually not needed. It's then not so surprising that keeping the interface as simple as possible for each web service method promotes the very advantages of JSON, making it quick and easy to use from JavaScript in a browser environment.
In general, keeping input parameters simple makes it easier to use. Remember that while SOAP developers can just point to the WSDL and automatically import the formal interface, JSON developers must be able to understand the interface by just looking at the documentation and examples, and then manually construct the request in JavaScript code. This is also why parameters encoded as part of the standard query string are preferred; they're simple, familiar, and easy to use, work like the rest of the web application and any other URL, and are also very easy to just copy and paste into a browser window to test and manipulate.