[tomc1985]

Tarpit or no, WSDLs are pretty complete interface documentation.

It's still weird to me that people see APIs as a "thing", worthy of attention from business types and other nontechnical money-men, And how is it that a "good API" requires client modules for all these different languages? Do people not know how to make HTTP requests anymore or something?

(On the client note: "But it makes integration easier" or "I'm lazy, screw your docs, gimme [gems|pips|npms]" is the usual response I hear, though, given that each of these calls represents an external dependency requirement, maybe its good that they aren't as easy to use as the rest of your language?)

[EdSharkey]

> And how is it that a "good API" requires client modules for all these different languages? Do people not know how to make HTTP requests anymore or something?

I look at a service like a plate of hors d'oeuvres across the room on a fancy table.

A client module (aka SDK) is the silver platter with the hors d'oeuvres neatly lined up for your selection, brought to you by the handsome waiter who is the only other person in the room who speaks your language.

One could walk to the table, and hardcore partygoers do, but lazy, entitled sacks like me prefer the delights to be hand-delivered. ;)

[tomc1985]

Til you realized those hand-delivered delights aren't particularly well made, and then grumble to yourself about how you coulda made them way better and faster in less time than them, maybe even less time than it would take to eat the food on your plate :P

[EdSharkey]

Yes, the promised 'delights' are too often frozen plainwrap food from Albertsons, barely defrosted in a dirty industrial microwave.

[devhead]

on the client note...

code reuse is why these clients exist, if you are a developer I can promise you that you are not issuing tcp requests by hand and instead prefer to use some standard library (curl) to handle that for you.

[tomc1985]

People don't seem to understand the entire spectrum of consequences that comes with so tightly integrating some cloud service on the other side of the web. That distance is an important detail that these client-gem implementations like to gloss over... because the same developer that reaches for said library may very likely be the same guy to use that gem in some tight inner loop, and then wonder why his app is so slow because get_base_id() has to roundtrip that distance multiple times to answer his question...

[teilo]

> And how is it that a "good API" requires client modules for all these different languages? Do people not know how to make HTTP requests anymore or something?

That is a complex question. For example, our company's ERP is a niche product specific to the printing industry. It has a SOAP API, and a WSDL so large that it will crush any SOAP library that is not doing code generation. We are one of only a handful of their customers who are NOT using their pre-generated SDKs because we do everything in Python and Elixir, and they only provide SDKs for Java, PHP, and .NET.

They rely upon the SDKs to provide API documentation, rather than the WSDL. The CRUD endpoints are consistent and work well - until they don't, and then you have to guess why a call failed due to some undocumented business rule. The process endpoints are a nightmare. Every call is documented as follows: Name, number of parameters. That's it. Parameters are all called IN0 through IN9. There is no documentation specify what the parameters are, which ones are required, what the data types are, or acceptable values/ranges. We have to dig through the SDK code (usually PHP) and make guesses.

To make matters worse, the state-side developers didn't write and don't maintain the API. It's offshored, and any question takes a couple weeks to get answered.

I realize that none of this is SOAP/WSDL's fault. But the fact that the vendor can get away with this shows how many shops really truly can't handle simple HTTP requests, and are hamstrung unless the vendor supplies an SDK. Otherwise the vendor could never get away with this.

As an aside: We ended up writing a REST microservice to translate JSON calls to SOAP for CRUD. (This was also necessary because we discovered that if we did not rate-limit the SOAP calls, the ERP choked). This dramatically simplified our integration code. But to this day, through we have repeatedly requested it, we cannot get full documentation on the process calls.