Odi's astoundingly incomplete notes
New entries | CodeFrom WS-* to REST/JSON
To set the frame, please note that during the last 10 years I have done a great many Webservices. In Java. Client and server side. Synchronous and asynchronous. Directly connected and decoupled via ESBs like TIBCO and queuing infrastructure like IBM MQ. And if I say a lot then I mean that a quick find in the git tree reveals about 1400 WSDL files. I have worked on most of them. Most of them use CXF. Some ancient ones use Axis.
Lately WS seems to be a dying technology. New interfaces between systems are now usually requested to use REST and JSON. This comes with much joy but unfortunately also much frustration.
This may seem like a joke. If plain text has one special power, then that you can insert comments. Except when the format doesn't allow it. Like JSON. This was a really brain-dead decision.
There is no standard for specifying an interface.
Well there are several competing technologies: Swagger, RAML, WADL to name a few. And then you can often chose to write them in YAML or JSON. If we wanted to support all those technologies, we would have use and maintain a zoo of tools. It would have really helped REST if it had standardized a single very good interface description language. For WS-* there is WSDL. And everybody was using it. And even though there was an option to use Relax-Ng as the modelling language, everybody just used XML Schema. Consequently the number of available tools is endless. You always find good tools that are a joy to use. Not so in the REST world. It's a chaos and a desert at the same time.
Some developers even think it is sufficient to provide some examples of requests and responses in a PDF. Of course simple typos lead to much cursing later and make testing a lengthy and painful experience.
Of course interface documentation is often also done by annotating an example message with comments. But wait... JSON doesn't have a syntax for comments, rendering such examples into invalid JSON. This is unnecessarily ugly.
Multiple competing conventions
Apparently people have noticed that REST is not enough of a spec to be actually useful. So multiple conventions have popped up that tell you how to build REST services: HAL, OData to name a few. Naturally each one claims to be the best one. Again if you need to integrate many different REST services you will have to support a zoo of 'standards'.
REST/JSON is unfriendly to strongly typed languages (like Java).
WS-* with XML Schema was equally horrible for dynamically typed languages (like JS). But there was no need to repeat that same mistake. Parsing is already harder than necessary. A JSON object has no name! It starts with a brace followed by a list of name/value pairs. So in a stream I have no idea what type of object I am going to look at and which properties I should expect. I have to know from some other source what I am going to parse.
Nothing prevents a system from throwing an array containing various types of objects at you. Without knowing exactly what type of object to expect at which array index there is simply no way of mapping that into an object model. You have to resort to a generic representation with maps which will cause you more pain later.
The number of defined datatypes in JSON is low, which I consider a good thing. But it lacks two things. There is no fixed-point decimal type. JSON's numbers are by default interpreted as double floating point numbers, which is inadequate for things like quantities or prices. Also it doesn't define any type for date and time. Most of the time though people use string and interprete it using the XML schema date format (ISO 8601). Given the difficulties involved with dates and timezones there is a need to have a good data type for date and time.
REST is not friendly to HTTP
REST is always advertised as being a natural fit for HTTP and how it embraces it's concepts. And then you find an HTTP method called PATCH that had to be standardized. Guess how many libraries still don't support PATCH 10 years later.
Have you come across a REST API that had a GET call that includes a REST object in its HTTP entity (body)? Guess how many middleboxes don't support that at all.
REST/JSON is not not good for RPC
A remote procedure call is a call that has an ordered fixed number of arguments whose types are constant and a single return value of constant type, with the assumption that arguments and return value are serializable. This definition matches function call definitions in all but exotic languages. That made it a hugely successful concept. WS-* extended it a little with Faults (exceptions) to ease integration with modern languages like C# or Java. Somehow the REST world decided that it should go a different route. Arguments in REST can be scattered throughout various places: HTTP methods (GET, POST, ...), HTTP headers (including Cookies), URI components, URL parameters and the HTTP entity (body message). Return values / objects usually depend on the HTTP status code. This could in theory be mapped to the simple RPC model, but I have yet to see any good infrastructure that does that well. JAX-RS is not nice here: all return values are simply a generic object, from which you extract the HTTP status code and then ask the object to interprete the return value as a specific type. Non-200 responses should have been mapped to exceptions in my opinion and the 200-response should have been chosen as the return type. But now we have this messy "generic" RPC style which is totally not type safe, which means that avoidable mistakes only show up at runtime instead at compile time.
Swagger doesn't even force the developer to define (named) types at all. You could simply list arguments and return types inline even if they are large complex objects. Code generators for typed languages have no other possibility than generate silly classnames (or let the poor developer specify them via configuration) in that case. Producing a horrible maze of classes that are hard to use. It's not what you want when the logic is already complex. Good names help.
REST/JSON is not good for messaging
By messaging I mean a classic ESB or message queue. So put the arguments to the RPC call into a file, possibly modify it, and send that file asynchronously over some transport queueing mechanism to the destination endpoint. For that to work you need the file to contain everything you need to know to execute the RPC call (except anything which is configuration like the actual endpoint URL of the destination). With WS-* that was part of idea behind it. It made very sure that the message contains the operation name (style: document literal wrapped) for example. Metadata (headers) is also part of the message.
All sorts of ESB middle ware cropped up. But also locally for an application it is essential to be able to queue messages to a remote system and send them one-by-one in a defined order or highly parallelize them, when the remote system is available and ready.
REST makes it harder. Because the REST/JSON message may not contain all information: again JSON objects have no name, more than one HTTP method could apply to the same arguments, some of the arguments could be part of the HTTP headers, URI or need to be passed in the URL parameter and may not be available from the message. If that is the case you need to wrap the message into an additional object that contains the missing information. As a design rule for ESB capable JSON objects, all information should be contained in the JSON object even if it is later partly duplicated elsewhere in the HTTP request.
Lately WS seems to be a dying technology. New interfaces between systems are now usually requested to use REST and JSON. This comes with much joy but unfortunately also much frustration.
Joys first
- Less traffic. Yey! JSON is much more compact than XML. It can make a huge difference.
- No more XML namespaces. It was the hardest thing for developers to understand and get right.
- No more XML at all. All these people assembling or parsing XML with string operations and all the associated headaches like missing escaping or broken namespace handling.
- No more XML parsers which are a trivial target for all sorts of attacks
- No more worrying about SOAP binding styles (document literal, RPC).
- No more worrying about SOAP versions or myriards of WS-* extensions.
Now for the frustrations
JSON does not support commentsThis may seem like a joke. If plain text has one special power, then that you can insert comments. Except when the format doesn't allow it. Like JSON. This was a really brain-dead decision.
There is no standard for specifying an interface.
Well there are several competing technologies: Swagger, RAML, WADL to name a few. And then you can often chose to write them in YAML or JSON. If we wanted to support all those technologies, we would have use and maintain a zoo of tools. It would have really helped REST if it had standardized a single very good interface description language. For WS-* there is WSDL. And everybody was using it. And even though there was an option to use Relax-Ng as the modelling language, everybody just used XML Schema. Consequently the number of available tools is endless. You always find good tools that are a joy to use. Not so in the REST world. It's a chaos and a desert at the same time.
Some developers even think it is sufficient to provide some examples of requests and responses in a PDF. Of course simple typos lead to much cursing later and make testing a lengthy and painful experience.
Of course interface documentation is often also done by annotating an example message with comments. But wait... JSON doesn't have a syntax for comments, rendering such examples into invalid JSON. This is unnecessarily ugly.
Multiple competing conventions
Apparently people have noticed that REST is not enough of a spec to be actually useful. So multiple conventions have popped up that tell you how to build REST services: HAL, OData to name a few. Naturally each one claims to be the best one. Again if you need to integrate many different REST services you will have to support a zoo of 'standards'.
REST/JSON is unfriendly to strongly typed languages (like Java).
WS-* with XML Schema was equally horrible for dynamically typed languages (like JS). But there was no need to repeat that same mistake. Parsing is already harder than necessary. A JSON object has no name! It starts with a brace followed by a list of name/value pairs. So in a stream I have no idea what type of object I am going to look at and which properties I should expect. I have to know from some other source what I am going to parse.
Nothing prevents a system from throwing an array containing various types of objects at you. Without knowing exactly what type of object to expect at which array index there is simply no way of mapping that into an object model. You have to resort to a generic representation with maps which will cause you more pain later.
The number of defined datatypes in JSON is low, which I consider a good thing. But it lacks two things. There is no fixed-point decimal type. JSON's numbers are by default interpreted as double floating point numbers, which is inadequate for things like quantities or prices. Also it doesn't define any type for date and time. Most of the time though people use string and interprete it using the XML schema date format (ISO 8601). Given the difficulties involved with dates and timezones there is a need to have a good data type for date and time.
REST is not friendly to HTTP
REST is always advertised as being a natural fit for HTTP and how it embraces it's concepts. And then you find an HTTP method called PATCH that had to be standardized. Guess how many libraries still don't support PATCH 10 years later.
Have you come across a REST API that had a GET call that includes a REST object in its HTTP entity (body)? Guess how many middleboxes don't support that at all.
REST/JSON is not not good for RPC
A remote procedure call is a call that has an ordered fixed number of arguments whose types are constant and a single return value of constant type, with the assumption that arguments and return value are serializable. This definition matches function call definitions in all but exotic languages. That made it a hugely successful concept. WS-* extended it a little with Faults (exceptions) to ease integration with modern languages like C# or Java. Somehow the REST world decided that it should go a different route. Arguments in REST can be scattered throughout various places: HTTP methods (GET, POST, ...), HTTP headers (including Cookies), URI components, URL parameters and the HTTP entity (body message). Return values / objects usually depend on the HTTP status code. This could in theory be mapped to the simple RPC model, but I have yet to see any good infrastructure that does that well. JAX-RS is not nice here: all return values are simply a generic object, from which you extract the HTTP status code and then ask the object to interprete the return value as a specific type. Non-200 responses should have been mapped to exceptions in my opinion and the 200-response should have been chosen as the return type. But now we have this messy "generic" RPC style which is totally not type safe, which means that avoidable mistakes only show up at runtime instead at compile time.
Swagger doesn't even force the developer to define (named) types at all. You could simply list arguments and return types inline even if they are large complex objects. Code generators for typed languages have no other possibility than generate silly classnames (or let the poor developer specify them via configuration) in that case. Producing a horrible maze of classes that are hard to use. It's not what you want when the logic is already complex. Good names help.
REST/JSON is not good for messaging
By messaging I mean a classic ESB or message queue. So put the arguments to the RPC call into a file, possibly modify it, and send that file asynchronously over some transport queueing mechanism to the destination endpoint. For that to work you need the file to contain everything you need to know to execute the RPC call (except anything which is configuration like the actual endpoint URL of the destination). With WS-* that was part of idea behind it. It made very sure that the message contains the operation name (style: document literal wrapped) for example. Metadata (headers) is also part of the message.
All sorts of ESB middle ware cropped up. But also locally for an application it is essential to be able to queue messages to a remote system and send them one-by-one in a defined order or highly parallelize them, when the remote system is available and ready.
REST makes it harder. Because the REST/JSON message may not contain all information: again JSON objects have no name, more than one HTTP method could apply to the same arguments, some of the arguments could be part of the HTTP headers, URI or need to be passed in the URL parameter and may not be available from the message. If that is the case you need to wrap the message into an additional object that contains the missing information. As a design rule for ESB capable JSON objects, all information should be contained in the JSON object even if it is later partly duplicated elsewhere in the HTTP request.
Add comment