6 ms·

SOAP is an absolute nightmare to work with. A WSDL is not even remotely comparable to Swagger. For one, Swagger is for humans not machines to consume. At it's

by throwaway2016a 8y ago

SOAP is an absolute nightmare to work with. A WSDL is not even remotely comparable to Swagger. 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.

scarface74 8y ago
Few implementations add hypermedia support in the real world. 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 https://github.com/Azure/autorest Java - https://github.com/swagger-api/swagger-parser/blob/master/README.md https://github.com/swagger-api/swagger-parser/blob/master/RE... And basically everything else. https://github.com/swagger-api/swagger-codegen/blob/master/README.md https://github.com/swagger-api/swagger-codegen/blob/master/R...
- throwaway2016a 8y ago
  Those are code generators. The code they generate is for the computer. The spec is still an abstraction layer designed for humans. 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.
  - scarface74 8y ago
    How is that any different than a WSDL? A WSDL could also be said to be designed for humans -- it's just XML -- but there are code generators for it too.
tannhaeuser 8y ago
I've been developing so-called "REST" services for over ten years (and SOAP services before that), and not even once were REST principles actually applied in the projects I worked on. As in, the client/browser discovers from an URL the interactions with a resource without out-of-band info for minimal coupling of client and service. I agree though getting SOAP/XML right takes typically considerably more effort than JSON. 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.
- throwaway2016a 8y ago
  > I've been developing so-called "REST" services for over ten years (and SOAP services before that), and not even once were REST principles actually applied in the projects I worked on. 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> But this will fail: <order> <price>19.95</price> <token>ABC</token> </order> Why the heck does the order of keys in my object make the API fail!? 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.
  - tannhaeuser 8y ago
    Ah ok. But to assemble XML/SOAP for these kind of payloads you'd typically be using a lib such as JAXB, Jackson/gson, Spring (for Java at least) or SCA anyway. 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.

scarface74 8y ago

Few implementations add hypermedia support in the real world. 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 https://github.com/Azure/autorest Java - https://github.com/swagger-api/swagger-parser/blob/master/README.md https://github.com/swagger-api/swagger-parser/blob/master/RE... And basically everything else. https://github.com/swagger-api/swagger-codegen/blob/master/README.md https://github.com/swagger-api/swagger-codegen/blob/master/R...

throwaway2016a 8y ago
Those are code generators. The code they generate is for the computer. The spec is still an abstraction layer designed for humans. 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.
- scarface74 8y ago
  How is that any different than a WSDL? A WSDL could also be said to be designed for humans -- it's just XML -- but there are code generators for it too.

tannhaeuser 8y ago

I've been developing so-called "REST" services for over ten years (and SOAP services before that), and not even once were REST principles actually applied in the projects I worked on. As in, the client/browser discovers from an URL the interactions with a resource without out-of-band info for minimal coupling of client and service. I agree though getting SOAP/XML right takes typically considerably more effort than JSON. 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.

throwaway2016a 8y ago
> I've been developing so-called "REST" services for over ten years (and SOAP services before that), and not even once were REST principles actually applied in the projects I worked on. 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> But this will fail: <order> <price>19.95</price> <token>ABC</token> </order> Why the heck does the order of keys in my object make the API fail!? 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.
- tannhaeuser 8y ago
  Ah ok. But to assemble XML/SOAP for these kind of payloads you'd typically be using a lib such as JAXB, Jackson/gson, Spring (for Java at least) or SCA anyway. 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.