[tannhaeuser]

What I said: it looks at the whole story, rather than piecemeally stitching together a stack. The downside is that it's maybe overwhelming, especially with multiple competing protocol specs and stacks doing the same thing.

As to XML: IMHO actually XML isn't a good fit for most API payloads. XML comes from markup languages/SGML which model semistructured data as regular content models, rather than co-inductive data structures of programming languages. The thing is, though, that the alternative, JSON, is really too basic (doesn't have schema-based validation, doesn't have date datatypes or enumerations, hell doesn't even have decimal numbers, etc.) Part of the story why JSON is so popular is that it's untyped and you don't have to agree on schemas, typed payloads, etc. upfront, and can just begin coding - but that also means you don't have typing, service contracts, etc. as your apps mature.

[chii]

The format of the api (and its' payloads) also depends on the purpose of the api.

If the api is meant to be tightly coupled to an app, and is designed for that specific purpose, there's no reason to use anything like xml (or even, json) - it should be compact binary and minimal footprint.

If the api is meant to be general and apply across a range of client environments (e.g., you're selling this service api, and you dont know how or what your customer might use it for), it makes sense to make an api that's using an open format (like json, or xml) and have easily able clients in multitude of languages.

[gnfurlong]

JSON Schema and Swagger/OpenAPI provide some of the missing functionality described above (type definitions, enumeration, validation). It's not quite the same and in particular I'm not sure I've seen a reference to the schema passed with the json itself (although that could easily be ignorance on my part).