Debugging is boring. Wouldn't you rather appeal to customers who write bug-free code on the first try?
To really show disdain for your customers, use a proprietary protocol so that language support is limited to the client libraries you provide, preferably as binary blobs that are never updated. If you design it carefully, a proprietary protocol can be difficult to understand and impossible to debug, too.
Alternatively, you can use SOAP (Simple Object Access Protocol). According to Wikipedia, SOAP "can be bloated and overly verbose, making it bandwidth-hungry and slow. It is also based on XML, making it expensive to parse and manipulate—especially on mobile or embedded clients" (https://en.wikipedia.org/wiki/SOAPjr). Sounds like a win-win!"
I remember when the early days of Amazon S3, trying to write Bourne shell scripts using shell built-ins and single purpose UNIX utilities to form the HTTP and interact with the servers, instead of scripting languages with libraries like Perl, Python, Ruby, etc. This is how I interact with HTTP servers normally. I never have any problems keeping things simple and dependency-free.
To do this with S3, it felt nigh impossible. There were small errors in their documentation of how things actually worked. It felt like they were intentional just to trip me up. I know they were not.
The official recommendation back in those early days of AWS was to use one of the protocol options provided by Amazon, HTTP or SOAP. You would think, heh, I will avoid SOAP and keep it simple. I will just use HTTP.
The truth is both required using scripting languages with libraries. Amazon's own utilities were written in Java. I know developers have their reasons for making these choices, but as a user, that complexity really put me off.
From my perspective, this ACM article is right on point.
"When I see a top-down description of a system or language that has infinite libraries described by layers and layers, all I just see is a morass. I can't get a feel for it. I can't understand how the pieces fit; I can't understand something presented to me that's very complex. Maybe I do what I do because if I built anything more complicated, I couldn't understand it. I really must break it down into little pieces." - Ken Thompson
http://genius.cat-v.org/ken-thompson/interviews/unix-and-bey...
That's a bit of a strawman. The cultural tradeoffs between "inspectable" JSON and "bloated" SOAP have to do with their most common consumption environment.
In my current life I work mostly with JSON and a typical workflow involves checking API documentations, querying the endpoints, and understanding the structure. I need to own the mapping between JSON and domain objects.
In a previous life I worked with .NET and C#, mostly SOAP APIs. A typical workflow involves right-clicking somewhere, pasting the link to the SOAP endpoint's WSDL file, and automagically getting a collection of strongly typed classes that I can manipulate directly and operate on as if they were domain objects.
The idea that when using SOAP one spends any time (manually) parsing and trying to make sense of XML is a misconception.
To put it in a modern parlance, one shouldn't compare SOAP to JSON. SOAP is JSON + Swagger, with the Swagger integration costing 0.
Some proprietary protocols are easier to implement than open ones. The other day I wrote against one API server that just accepts messages in json format over an ssl socket. It was maybe 3 or 4 lines of python? (Not counting setting up the connection) and probably wouldn’t have been bad in C. For the shell you could use OpenSSL s_connect and something to generate json (awk or echo would probably be enough since it was all flat dictionaries of strings.)
> There were small errors in their documentation of how things actually worked.
that sucks, but I’ve run into that with people speaking “http” and not just special protocols.
Debugging is boring. Wouldn't you rather appeal to customers who write bug-free code on the first try?
To really show disdain for your customers, use a proprietary protocol so that language support is limited to the client libraries you provide, preferably as binary blobs that are never updated. If you design it carefully, a proprietary protocol can be difficult to understand and impossible to debug, too.
Alternatively, you can use SOAP (Simple Object Access Protocol). According to Wikipedia, SOAP "can be bloated and overly verbose, making it bandwidth-hungry and slow. It is also based on XML, making it expensive to parse and manipulate—especially on mobile or embedded clients" (https://en.wikipedia.org/wiki/SOAPjr). Sounds like a win-win!"
I remember when the early days of Amazon S3, trying to write Bourne shell scripts using shell built-ins and single purpose UNIX utilities to form the HTTP and interact with the servers, instead of scripting languages with libraries like Perl, Python, Ruby, etc. This is how I interact with HTTP servers normally. I never have any problems keeping things simple and dependency-free.
To do this with S3, it felt nigh impossible. There were small errors in their documentation of how things actually worked. It felt like they were intentional just to trip me up. I know they were not.
The official recommendation back in those early days of AWS was to use one of the protocol options provided by Amazon, HTTP or SOAP. You would think, heh, I will avoid SOAP and keep it simple. I will just use HTTP.
The truth is both required using scripting languages with libraries. Amazon's own utilities were written in Java. I know developers have their reasons for making these choices, but as a user, that complexity really put me off.
From my perspective, this ACM article is right on point.
"When I see a top-down description of a system or language that has infinite libraries described by layers and layers, all I just see is a morass. I can't get a feel for it. I can't understand how the pieces fit; I can't understand something presented to me that's very complex. Maybe I do what I do because if I built anything more complicated, I couldn't understand it. I really must break it down into little pieces." - Ken Thompson http://genius.cat-v.org/ken-thompson/interviews/unix-and-bey...