I had to use SOAP once... for one API endpoint.

I'd say it was the worst dev experience of my whole career, and I fought with objective-c and app stores.

Using SOAP APIs daily since over 15 years with .NET Framework development. Simple and easy to write and then easy to consume through Visual Studio generated code.

Tried some ObjC development early on the iPhone. Gave up quickly.

I agree that SOAP looks like a mess. But given the right tools, it honestly just works. Never had a single issue with these APIs apart being stuck in .NET Framework land.

Been using it daily myself for just as long with VS. Being basically exclusive to .Net is a huge set back. I would never make a new SOAP services these days. There are other solutions that just work with far less complexity, waste, and limitations.

And that's the issue.

SOAP isn't some nice standardized language-agnostic API layer.

SOAP is .NET/Visual Studio RPC. (Not technically, but in practice, due to its complexity.)

And hey, great for you. But a lot of people want APIs to be broadly compatible.

> SOAP isn't some nice standardized language-agnostic API layer.

What? Of course it is (well, it's a messaging protocol). Where on earth did you get the idea that it's some Microsoft-only proprietary technology?

You missed the word "nice" in the GP's message. Also "(Not technically, but in practice, due to its complexity.)"

No one says it is proprietary technology and yes, it is nominally standardized. It is just so complex that it is impossible to use without heavy tooling support, and this tooling is only really usable in Microsoft's technology.

So it seems that people who use MS ecosystem like SOAP ... while almost everyone else who tried it calls is over-complicated, incomprehensible and "worst dev experience of my whole career"

> It is just so complex that it is impossible to use without heavy tooling support, and this tooling is only really usable in Microsoft's technology.

Again, gotta call BS here. My early career was 100% SOAP and related WS-* technologies. And it was all in Java, Apache Axis and friends. Wildly popular at the time. Give it your WSDL, out pops a nice Java client. People didn’t like it not because it was difficult to use outside of the Microsoft ecosystem, they didn’t like it because it was the concepts were difficult to understand and there were many complicated technologies piggybacking off of it. It was hard to debug issues, Visual Studio or not. If you had to do something that a generated client could do, it was difficult, Visual Studio or not.

Try calling a soap service with python. Oh boy enjoy the pain!

"it honestly just works"

Which I would agree is most of the time - but then it doesn't and you have to try and work out what is going wrong from reams of impenetrable generated WSDL. Which is fun.

Yes, I had to use it in a Node.js project.

Would imagine, with the right tooling and TypeScript it wouldn't have been that bad.

Looks like a case of Stockholm syndrom.

Over the past year I’ve built an ESB for a client’s deployment of a brand spanking new distribution management system … which you could integrate with only and solely using SOAP. The tooling in Java makes it bearable, but I am still shocked that this system deployed in 2021 has this.

I did XSD validator back in 2003 and indeed this blog post gives me familiar vibes.

I do believe there has to be some sort of common schema format, but I have no idea how this problem could be solved cleanly in practice, even after 20 years.

And the tools have trouble too. For instance: Java axis2 generating non-deterministic class names (Product1 in one compilation, Product0 in another compilation after).

Well let's turn the statement around then: can you create a OpenAPI YAML by hand then? At least with XML and XSD you have proper auto complete.

I really no need see the need to use a schema for JSON. The only thing it has going for it compared to SOAP/XML is the fact the it faster parsing and that it has no schema.

I can certainly create a JSONSchema (the XSD equivalent) by from memory (except for the $schema URI):

    {
      "type": "object",
      "properties": {
        "foo": { "type": "string" }
      }
    }

And at least in VSCode, I get autocomplete too.

OpenAPI...I personally don't use this as much but yes there are hundred tutorials on creating definitions by hand.

Yes, you can. Since OpenAPI itself has a JSON schema, you can get autocomplete from any editor that supports JSON schema.

At my company, we found that the auto-OAS generation tools were too brittle and didn't communicate enough information, so we actually do write our own OAS and run automation to make sure it's accurate.

That's also how our architects communicate with developers about an endpoint - create an OAS for it.

> At my company, we found that the auto-OAS generation tools were too brittle and didn't communicate enough information, so we actually do write our own OAS and run automation to make sure it's accurate.

I found all OAS spec authoring tooling to be useless toys when building non-trivial real world specs.

The depths of depravity I’m forced to is as follows:

1. Data model in SparxEA because it’s the tool we have in the depths of govt. Generate XSD from tool

2. XSLT to turn the XSD into matching JSON Schema because I’m old and can still remember how.

3. Hand write the OAS with $ref into JSON schema as appropriate

4. Curate sample payloads to be educationally useful

5. Generate CURL and various code samples

6. Bundle it all into approx 80k lines of machine written wondrousness -

7. ReDoc and Mkdocs to build static website with more documentation

All the work is at data modeling, OAS sample curation and mkdocs documentation

Things I wish JSON and Schema had:

1. An equivalent of xs:decimal that JS would use number & double are just plain useless in real world commerce with dollars & cents and bulk item pricing with 3&4 decimal places

2. Has taken the time to fix rfc3399 and give Dates a Timezone suffix. Too many languages Marshall a date into datetime. How many bugs have I seen where it’s broken in the morning and works in the afternoon because the damn server is running in AU with UTC Timezone and we’re in NZ

> can you create a OpenAPI YAML by hand then?

Of course.

> At least with XML and XSD you have proper auto complete.

Tooling for OpenAPI exist. In VS Code for example.

> I really no need see the need to use a schema for JSON

Don't you see the need for precise machine readable description of JSON input and output for a REST API for validation? This is OpenAPI..

You can get proper autocomplete out of OpenAPI, powered by typescript.