4 ms·

This reminds of the SOAP/WSDL days. The lesson learned from those days is that if your API is complicated enough that you are needing to use such tools, then y

This reminds of the SOAP/WSDL days. The lesson learned from those days is that if your API is complicated enough that you are needing to use such tools, then you should really do some analysis into how you can simplify your API.

chrismorgan 9y ago
It’s all about having a machine-readable definition of the API. When you have that, you can support strictly-, strongly-typed languages much better. In a language like C, Java or Rust, which would you rather: a JSON data type that is essentially Map<String, Object>, or a struct (or class, or whatever) that actually represents the fields and types that exist? It’s useful to be able to quickly generate a client library with fair ergonomics for such languages, rather than having to use a weakly-typed, string-heavy general-purpose HTTP library. Languages like JavaScript, Ruby and Python don’t benefit so much from things like this, but even so there are definite advantages to it.
- vesak 9y ago
  https://github.com/metosin/compojure-api https://github.com/metosin/compojure-api this library uses clojure.spec with Swagger APIs to check data validity.
organsnyder 9y ago
Your API is a contract you're extending to your customers. You need to be able to specify the behavior of a given operation with enough precision that you and your customer have a good understanding of how it will work. The problem with SOAP/WSDLs is that you break the contract every time you sneeze at the damn thing (adding a field, etc.). Swagger/OpenAPI is generally more permissive, as long as you know what you're doing. API versioning is hard, regardless of the tool you use. Contract-first API design prioritizes predictability over fluidity. The decision on which trade-offs are correct will depend on the context.
niftich 9y ago
On the contrary; the lesson learned from those days is that codegens and declarative inputs to codegens (i.e. API specs) have their place, despite the particular stack falling out of fashion. APIs that were put out when the "RESTful" movement was at its peak were documented solely in prose, a big regression from the WSDL days. OpenAPI (or a few years ago, Swagger and its contemporaries RAML and API Blueprint) attempt to retrofit what we've lost. Spec-driven codegens allow shops that put out APIs to quickly bootstrap first-party clients, gaining an instant competitive advantage over similarly-positioned competitors who don't publish a first-party client.
- icebraining 9y ago
  So why not keep using SOAP and WSDL?
  - organsnyder 9y ago
    SOAP vs. REST is not simply XML+WSDL vs. JSON+OpenAPI. REST is resource-focused, where SOAP is operation-focused. REST takes advantage of HTTP's built-in features (verbs, caching, etc.) in ways that SOAP doesn't (SOAP is basically RPC tunneled over HTTP POSTs). I work on an API team that is in the early stages of switching from SOAP services to REST (using Swagger/OpenAPI). Shifting mindsets from RPC-based to resource-based APIs is challenging, but very beneficial (of course, there are still use-cases for RPC-style APIs).
    - icebraining 9y ago
      Ah, then I had a misconception of OpenAPI; my perception is that it was mostly used by people who wanted to use REST like how they used SOAP (using URLs and such but still fundamentally RPC). Does that mean OpenAPI lets you model and describe a real hypermedia application, following the REST constraints? Including ignoring the URLs and focusing on media representations and their relationships?

chrismorgan 9y ago

It’s all about having a machine-readable definition of the API. When you have that, you can support strictly-, strongly-typed languages much better. In a language like C, Java or Rust, which would you rather: a JSON data type that is essentially Map<String, Object>, or a struct (or class, or whatever) that actually represents the fields and types that exist? It’s useful to be able to quickly generate a client library with fair ergonomics for such languages, rather than having to use a weakly-typed, string-heavy general-purpose HTTP library. Languages like JavaScript, Ruby and Python don’t benefit so much from things like this, but even so there are definite advantages to it.

vesak 9y ago
https://github.com/metosin/compojure-api https://github.com/metosin/compojure-api this library uses clojure.spec with Swagger APIs to check data validity.

organsnyder 9y ago

Your API is a contract you're extending to your customers. You need to be able to specify the behavior of a given operation with enough precision that you and your customer have a good understanding of how it will work. The problem with SOAP/WSDLs is that you break the contract every time you sneeze at the damn thing (adding a field, etc.). Swagger/OpenAPI is generally more permissive, as long as you know what you're doing. API versioning is hard, regardless of the tool you use. Contract-first API design prioritizes predictability over fluidity. The decision on which trade-offs are correct will depend on the context.

niftich 9y ago

On the contrary; the lesson learned from those days is that codegens and declarative inputs to codegens (i.e. API specs) have their place, despite the particular stack falling out of fashion. APIs that were put out when the "RESTful" movement was at its peak were documented solely in prose, a big regression from the WSDL days. OpenAPI (or a few years ago, Swagger and its contemporaries RAML and API Blueprint) attempt to retrofit what we've lost. Spec-driven codegens allow shops that put out APIs to quickly bootstrap first-party clients, gaining an instant competitive advantage over similarly-positioned competitors who don't publish a first-party client.

icebraining 9y ago
So why not keep using SOAP and WSDL?
- organsnyder 9y ago
  SOAP vs. REST is not simply XML+WSDL vs. JSON+OpenAPI. REST is resource-focused, where SOAP is operation-focused. REST takes advantage of HTTP's built-in features (verbs, caching, etc.) in ways that SOAP doesn't (SOAP is basically RPC tunneled over HTTP POSTs). I work on an API team that is in the early stages of switching from SOAP services to REST (using Swagger/OpenAPI). Shifting mindsets from RPC-based to resource-based APIs is challenging, but very beneficial (of course, there are still use-cases for RPC-style APIs).
  - icebraining 9y ago
    Ah, then I had a misconception of OpenAPI; my perception is that it was mostly used by people who wanted to use REST like how they used SOAP (using URLs and such but still fundamentally RPC). Does that mean OpenAPI lets you model and describe a real hypermedia application, following the REST constraints? Including ignoring the URLs and focusing on media representations and their relationships?