51–60 of 163 posts
Defining a DSL is almost alway a better idea (but more difficult) than defining a configuration format.
Earlier quoted context omitted.
Do people write Swagger files by hand? That sounds awful. I was under the impression everyone used tools like I use in Clojure (compojure-api[0] and ring-swagger[1]). [0] https://github.com/metosin/compojure-api [1] https://github.com/metosin/ring-swagger
I didn't realize Swagger was meant to be an intermediate format.
My problem with Swagger is almost the opposite... it solves the problem (APIs are very complicated to use!) by embracing this complexity with more complexity and more tools. Rather, I believe the solution is a push to just have simpler APIs. It's crazy to me that it's harder to write a Swagger file than it is to write the API itself. And there's a lot of tooling that benefits from Swagger, but... I've found they all…
Are there any good alternatives? I used REST which forced me basically to dig deep into online documentation when I wrote a client, but was rather straight forward to implement a server with. I used SOAP which forced me to write a giant WSDL file, but was rather nice to work with on the client side. GraphQL seems to obliterate this problem with its auto discovery mechanisms, but I don't know too much about it.
Earlier quoted context omitted.
A few counterpoints as I drift by: The HAL hypermedia format is in use at Comcast, powering the Xfinity TV API. Not only does it take advantage of hypermedia and HATEOAS, it also splits requests/responses in order to make the most use of HTTP caches. https://boston2016.apistrat.com/speakers/ben-greenberg Dunno if you're serious about not seeing how one could write a HATEOAS-driven client library or if I'm being troll…
I'm definitely not trolling - it's just that's not how clients work. I don't write a client by doing a random walk through the API until I get to the information I need, I want to call the API that I know I need to give me the information that I want, and for performance, I want it all to be returned on a single call ideally. e.g. If I want user B's playlist, I don't want to have to crawl: /friends/ => ['b': { 'links…
Sometimes you do a few more web calls than you might otherwise. If you can get away with it then great! Because the benefits are plenty
Hell! Even just having the uri of where the resource came from is useful enough. That's before you've introduced related resources.
Earlier quoted context omitted.
> Optimizing for HATEOAS seems to me to be optimizing for entirely the wrong metrics, and a complete waste of development time and effort. It depends, it's just a way to reduce coupling between a webservice and its client apps. Instead of hardcoding all the URL endpoints into the client, the client has to follow the links provided by the webservice instead. If this layer of indirection has advantages for you depends…
If I remove the reference to a link in the response, it doesn't remove the clients need to: a) know how to retrieve that link (i.e. what resource do I need to retrieve in order to get that response) b) requirement for that link to exist (they still need that link). Requiring that a client know that to get data Bar, they need to retrieve resource A, follow the link at foo[n]._link to retrieve resource B, and then foll…
Earlier quoted context omitted.
I agree that HATEOAS is never deployed anywhere, but I think I'd go further than that. It's impossible for me to see how it would be possible to write a HATEOAS client, and I can't in practice see anyone doing so. Optimizing for HATEOAS seems to me to be optimizing for entirely the wrong metrics, and a complete waste of development time and effort.
every web browser you use is a hateoas client you get some html with embedded links and then the browser automatically goes and fetches css, js, images... the remaining links it just presents to you, the user, to follow or not as you choose hateoas is not a complicated idea. it's not meant to replace SOAP or gRPC or thrift. it's something else
The HATEOAS idea is that you throw that out, just use some aribitrary XML (sorry, "hypermedia") to return your application state, and that this somehow magically empowers the client to be able to puzzle out all the things that can be done to your state.
Except it can't. It's just arbitrary junk if you don't have a schema and a spec. And it will always be so. Discoverability is (1) not something you can get from a data structure and (2) something best provided by documentation, not runtime behavior.
In terms of API documentation, the biggest problem is making sure the documentation is in sync with the actual code. I'm looking into using JSON Schema [1] along with Swagger and Dredd [2]. Making it all language-agnostic is a key. If anyone is doing anything similar, please, share your experience. [1] http://json-schema.org/ [2] http://dredd.readthedocs.io/en/latest/
I know this sounds awesome but in practice, it's really useful to have my swagger UI exposing the endpoints for our front-end developers to consume. What a pain it'd be for me to tell them "hit / and see what you get!"
Having HAL links between resources is great and this discovery aspect of HATEOAS makes a lot of sense in development. But having a single entrypoint "homepage" to the API, when it comes to swagger, doesn't make sense.
I ran into this when I asked another department for the endpoint to hit for certain data. I was given a swagger page with a bunch of "/status" endpoints that would then reveal additional endpoints. Who knows what rabbit hole I was sent down. I just needed the endpoint and the necessary parameters.
If I were a third party or some outside developer consuming the API, it kind of makes sense. But our internal swagger docs really should reveal endpoints. I would feel like a big asshole if I asked my front-end co-worker to just "hit /status" and see if you get what you need!
Disclosure: I don't use Swagger codegen. I only use the Docblock markup to document my API and generate the swagger.json that I display on our docs page.
My problem with Swagger is almost the opposite... it solves the problem (APIs are very complicated to use!) by embracing this complexity with more complexity and more tools. Rather, I believe the solution is a push to just have simpler APIs. It's crazy to me that it's harder to write a Swagger file than it is to write the API itself. And there's a lot of tooling that benefits from Swagger, but... I've found they all…
I've implemented Swagger with several APIs and agree that it's crazy complex and time-consuming to write Swagger files manually. I believe the best use-case for Swagger is to develop the API (perhaps just defining the routes with payload and response, but without controllers), and then auto-generating the Swagger files. This way the API consumers always have an up-to-date documentation, and there is only one place wh…
My problem with Swagger is almost the opposite... it solves the problem (APIs are very complicated to use!) by embracing this complexity with more complexity and more tools. Rather, I believe the solution is a push to just have simpler APIs. It's crazy to me that it's harder to write a Swagger file than it is to write the API itself. And there's a lot of tooling that benefits from Swagger, but... I've found they all…
Do people write Swagger files by hand? That sounds awful. I was under the impression everyone used tools like I use in Clojure (compojure-api[0] and ring-swagger[1]). [0] https://github.com/metosin/compojure-api [1] https://github.com/metosin/ring-swagger
1) Many people use Swagger to design (rather than document), meaning the Swagger comes before the code
2) Most people just prefer to write it out, since the tooling otherwise isn't necessarily great (especially for non-developers)
We ran a poll and "by hand" (either on Swagger Hub/Apiary, or locally) won by a landslide.