At least with current JSON and REST API I stand a good chance of experimenting using just an editor and curl - good luck trying that with SOAP.

REST is getting there.

My experiences with SOAP were that 99% of the time it was fine - but those other 1% seems to take the other 99% of my time... ;-)

In many cases, I'll simply formulate xml requests myself and use a generic http request client because the implementation ended up being simpler & easier to maintain than all the confusing hacks I had to do to make zeep or suds (the most popular SOAP clients implemented in python) function properly.

[1] - https://github.com/modern-project/modern-ruby

   string DoStuff(string params)

WSDL is the ultimate api :) it would make my day to see the wsdl comeback of 2018

But since they provided WSDL before, their "REST" APIs now come with WADL files that offer zero value to anyone. Swagger would be a massive step up from that.

Except you can ignore the schema and swagger and have it just be simple, if that's all you need.

The biggest problem with SOAP is that it is too easy for the service provider to just dump their internal data structures without any thought to how it should be serialized for people using the data. XML is Particularly nasty in this regard, because it doesn't map well to the data primitives of most dynamic languages.

That said, I usually just treat SOAP APIs as if they were REST. By writing a class, and some wrapper methods for the parts I need. Instead of trying to consume the WSDL and use it the way they envisioned I would. Then again, if Python had better SOAP support I probably wouldn't even do that.

For one, Swagger is for humans not machines to consume. At it's core it is a way to standardize documentation that can be easily displayed to humans. WSDL is not only used by humans but also by client and server apps.

REST APIs themselves if done right though hypermedia can be self-documenting and require no download of large spec files to use it.

SOAP also suppers from a number of quirks. One for example, that order often matters. Yes you can write a WSDL that doesn't require order but nothing is worse than having a bug because <price> has to appear after <token> but before <expirationMonth> and any other order throws anon-specific validation error. Yes, I know there are tools that can help with this but I have never felt compelled to download a tool for REST. Curl does just fine for me. And to top it off a lot of the best SOAP tools are Windows only.

What I think you really should be pointing at is RPC (of which SOAP is a terrible no good implementation of). RPC indeed offers some benefits over REST and can even be simpler. At the expense of losing the discover and hypermedia aspects of REST if done right.

Re: statefulness ("order matters"): there are intrinsical stateful processes that aren't represented adequately by a REST service. Think of a basic "Purchase Order" resource representing purchased items on an e-commerce website. You generally can't add and delete line items freely once you have placed your order, but you may cancel individual items (unless they're already physically on your way), you may RMA items, etc. Representing this as a flat "Purchase Order" resource with GET, POST, DELETE, PUT primitives is useless as it isn't telling your web shop front-end developers what actions are available at any one time.

As a consultant who has talked at conferences on APIs and is brought in to explicitly fix these kind of issues I have seen a lot of this too but correct REST APIs do exist. I know because my team builds them.

You're experience is anecdotal and as is mine. But just because a lot of people assume REST is something it isn't doesn't mean REST is inferior to SOAP.

> Re: statefulness ("order matters")

My order matters comment had nothing to do with statefulness. I mean in the XML. In SOP this might work:

  <order>
    <token>ABC</token>
    <price>19.95</price>
  </order>

  <order>
    <price>19.95</price>
    <token>ABC</token>
  </order>

Granted that is not a limitation of SOAP but more XML schemas in general. Json is more likely to be order of values agnostic.

But to play devil's advocate I can see the argument where if you are using SOAP to make multiple RPC calls in the same envelope than order is important.

Moreover, you could design your XML Schema such that both variants are accepted (using XSD "all-groups"), though typically record-like data structures are indeed described using XSD sequences which would cause the issue you mentioned. Again I agree XML/XSD isn't a great payload/schema mechanism for data structures such as maps; after all SGML/XML was invented for encoding text. It's being used because it was the first mechanism on the scene, and it continues to be used because it's still much more capable and mature/established in terms of data validation than anything JSON, especially for protocols used in communication with external partners/banks/authorities.

For one, Swagger is for humans not machines to consume. At it's core it is a way to standardize documentation that can be easily displayed to humans.

c# - https://github.com/Azure/autorest

Java - https://github.com/swagger-api/swagger-parser/blob/master/RE...

And basically everything else.

https://github.com/swagger-api/swagger-codegen/blob/master/R...

I am not aware of any code generators that read the swagger file every single API call and use that as if it were the code.

This is not necessary in many languages that centre around domain objects. The validation is done automatically when the JSON gets mapped back to the object. It's far better than JSON schema anyway since you can enforce whatever custom validation you like.

> Then they realized that they needed some method to make a REST Api discoverable

But it doesn't have to be discoverable. And if you do want it then you could write the documentation by hand or expose a simple REST index endpoint.

> Now we are right back to being as complicated as SOAP.

You chose to make it complicated though.

IMO, the value of JSON Schema isn't that you have no validation that exists outside of JSON Schema, the value is that you can front load a TON of the validation into it, and share that vocabulary between your services. If you publish a JSON Schema about your endpoint, I can read that or feed it into tooling to produce a form to consume it. As someone working on the Elixir JSON Schema lib currently, the places where we COULDN'T express the validation with JSON Schema were often more interesting.

Like all documentation written by hand, it rapidly gets out of date with the actual implementation if you're not careful.

Also tools can automatically create proxy classes from WSDL's and now Swagger endpoints.

Which is silly, because REST is discoverable by definition, since you should be using hypermedia. And if your API is not discoverable, that's a good sign your service is not actually REST.

That's pretty much what I said! Web frameworks don't help you at all in this regard, which is why REST is unncessarily difficult to implement. Most web frameworks give you just enough for HTTP-based RPC.

As for the nightmare of REST, the real question is whether this difficult is intrinsic, or merely a product of immature tooling and poor understanding. No web framework I've seen, apart from the Waterken server, actually helps you achieve REST. They're largely all HTTP-based RPC frameworks.