Mike Amundsen

Maybe the following links can help in understanding hypertext/hypermedia? http://amundsen.com/hypermedia/hfactor/ https://gtramontina.com/h-factors/

There are ready-made mediatypes to communicate collections; some have even been registered as mediatypes with IANA. A simple one that would meet your needs is Collection+JSON [1]. There are others. This blog post [2] from 2014 lists some from a hypermedia perspective, although you may find some of these formats excessive for what you're trying to accomplish. Before JSON became a favorite for HTTP APIs, there used to be XML-based ones as well. AtomPub is a very good protocol, which defines an 'application/atomcoll+xml' mediatype for collections [3] [1] http://amundsen.com/media-types/collection/ [2] http://sookocheff.com/post/api/on-choosing-a-hypermedia-format/ [3] http://bitworking.org/projects/atom/draft-ietf-atompub-protocol-04.htm…

Hasn't this idea already been explored with registering media types? Isn't this what REST and all of the HTTP specs were meant to address? You use an existing hypermedia type or register a new one, then any client that can read those media types can read your API. I really think one day down the road, someone will come out with a great "new" architecture and it will be what was outlined in REST. As a side note, I went looking through many of these and they pointed to Swagger documents, which contained lots of URLs. This seemed to be a relevant article on the pitfalls of doing this along with some ideas on moving forward: http://amundsen.com/blog/archives/1147

I saw a talk about node.js by Mike Amundsen the other day - he did all his work using http://c9.io/ etc The IDE seemed a bit flaky, but quite powerful - the concept certainly seems promising. http://www.amundsen.com Having said that, for me personally I still prefer a very responsive UI, lots of keyboard shortcuts, and the kind of workspace / UI customization you can only get from desktops nowadays.

Basically 'naming things'. It makes it possible to address and distinguish strategies in writing and conversation. H-Factors ( http://amundsen.com/hypermedia/hfactor/ ) have also been useful to me in the past for the same reasons.

Now that you bring it up, the JSON API specification does not even mention REST or hypermedia actually. What I was trying to get at is that media types don't have to be coupled to the protocol. One can exchange an HTML document over HTTP just as easily as one could transmit that document over another protocol. Some media types do consider their applicability over multiple protocols, for example: http://amundsen.com/blog/archives/1151

Wouldn't (most of) the shortcomings of HAL you mention, be overcome by Collection+JSON [0]? It seems better suited as an already existing media type that accomplishes what you try to do with JSON API. [0] http://amundsen.com/media-types/collection/

Why do you say "Hopefully it will not become hypermedia" with respect to JSON? What's wrong with this happening? What are your thoughts on the Collection+JSON hypermedia type presented in Amundsen's book? http://www.amundsen.com/media-types/collection/

According to Steve Klabnik, this can be accomplished via GET forms and using query templates: http://amundsen.com/media-types/collection/format/#query-templates

> Also, is there a standard way to make discoverable the http methods that can be applied to a resource? HTTP OPTIONS method is exactly that. Mind your response headers, they can convey plenty of information about your resources: allowable methods, request and response types mime-types (you can rank type preference as well). > In practice, does anyone write web service clients that use, and are driven by, link discovery? ... Documentation is always useful. But HTTP can almost be self documenting for well thought out and linked resources. For link discovery, maybe a standard like HAL (http://stateless.co/hal_specification.html) or similar would be of interest. There is another proposed way as well, I can't think of it at the moment but will add an edit if/when it comes to me. EDIT: I had poor wording, there are several 'json hypermedia specifications'. Another would be (Collection+JSON http://www.amundsen.com/media-types/collection/). Hope that helps.

I'm not sure about a format just yet, but I'm fairly certain it would be a superset of edn (as opposed to imposing it on "plain old edn"). The Document Format spec for Collection+JSON is probably not a bad starting point: http://amundsen.com/media-types/collection/format/ Seems like it could readily be adapted to edn syntax. But I find myself drawn to the RDF concepts underlying JSON-LD, and wonder if the C+J and LD ideas could be melded together. A solid exploration of the larger concepts involved in hypermedia controls can be found in Mike Amundsen's recent book: Building Hypermedia APIs with HTML5 and Node http://shop.oreilly.com/product/0636920020530.do The basic idea is that, per Fielding, HATEOAS is an aspect of REST that shouldn't be ignored. Standardized media types with well-defined hypermedia controls allow clients that understand those standards to make state transitions without having to "know other rules" that aren't contained in the representations themselves. Our web browsers do this all the time when we click on links and submit forms that we find in web pages. Based on the X/HTML standard, ours browsers (hypermedia clients) know what to do with links and forms, i.e. how to initiate the appropriate state transitions (build and run GET/POST requests) based on the markup semantics. Now, if a client is driven programmatically (i.e. not by a human reasoning about the appearance and purpose of a form-button labeled "login", etc.) then you need a bit more…