mike amundsen has a few concrete examples on his github: github.com/mamund (like he uses in his book Building Hypermedia APIs with HTML5 and Node — this < is on libgen dot rs — and more recently in Design and Build Great Web APIs), or amundsen's Hypermedia-Oriented Design paper: w3.org/2011/10/integration-worksho...
ofc, you'll run into many competing structures, Collection-JSON, HAL, Siren, etc., but lots of competition is exactly a vibrant scientific field, maybe... /me shrugs
honestly, i'd say it's less of a technical thing, tho tech is involved in highly unique and complicated ways... but one way i think about it is that it's just steganography, but in this case the "secret" message inside the message (or media) is as structured and complicated as a web application or component itself. in a sense, everything has a "Source" that can be viewed to reveal embedded links
to an extent, yes, i think the "actions" decomposition of RPC (/customer/add) and OOP (/customer POST) and URL (/customer?add) all are options. but hypermedia is about putting links in the payload. if links are not in the response as a representation, however the URL looks doesnt so much matter. that comes down to CQRS, event sourcing, RPC, CRUD, etc. hypermedia wants to be in the response of the server, which entails that the response have links, not just properties. less or no nesting is a result of REST: fielding thinkings low nesting is good for distributed control, but hypermedia doesn't so much care as it is one way or another. but nested JSON or XML isn't HATEOAS, nor technically REST. nested queries neither, not even as request metadata. that's all one idea or another about databases and the hidden tax of Big O notation/syntax on queries as it relates to nesting. but hypermedia kicks in which not only is the response text, structured (markdowns), and includes image data (media) or video data (media), but as soon as HTTP protocol is introduced into the response itzelf, whatever it is. now we are not just sending messages, encrypted, secret, political, scientic, amorous, artistic, etc. but it isn't even just data, but it has aboutness: the quotation mark is now like a Quine quote[1]
those links are expressed as actions. sometimes they are CRUD, sometimes they are RPC, but they could be so much more. they could metadata about the API itself, as we see with HTTP OPTIONS0, they could be links to ledgers in cyberspace that are embedded inside other media, etc. that are inside torrent or magnet link file lists. the "read me" of the warez cracking tool could link to a wallet, or be the wallet to promote seeding the torrent and people can use wallet keys to unlock it to expend for their hosting for it in a signing party.
in any case, to an extend, yes it involves putting RPC style actions in a payload. that is exciting, like objects that could potentially operate each other. the link is there. all you have to do is query it, instead of find the result in the API and infer from result set or URL if you can POST there. does /user/ always entail i can create a user at that URI? will it be an affordance, a resource (AWS, k8s, etc. enter here with namespacing properties), a plain object or raw text data with no links?
you could have interfaces and menus as links, ofc. the entire game could be hyperlinks, but they would be on the DOM items themselves in the engine, discoverable properties and actions that other bots could cache and reason about, or that we could obviously automate too: we'd be automating affordances (configurations on HTML responses or JSON response that are properties for "safety", "mutability", "idempotence", "presentation") but all the properties of the hypermedia factors too. the hypermedia factors should be in responses in order for the API to be called RESTful, since they are evidence of its achieving Caching, Statelessness, etc. (its other constraints). so now our response not only needs structured text that may or may not be nested: it needs certain properties like [title], [method], action, [type], [rel], href, [name], src and possible [value]s. the response has these properties which give us confidence the API has a uniform interface, representation as a basis for resource manipulation, but are any of the values actually links? when they are values, and logics of the server support them, do they become RESTful. the links could point to anything: results in a google map, creation page for a payment, they could actually process as their methods if all the right conditions are in place for the link affordance to hold for that authorized key or user or session, etc. but more: [enctype] and [accept] are expected in the payload.
but more than this: [type] now includes semantics about the URL itself for values: semantic, safe, unsafe, idempotent.
so now affordances not only contain links to and about the nested or unnested architecture, which may or may not be actions, but we are including properties, metadata and navigational properties, links, but hypermedia controls which could be about the resource or the data or the object or the affordance itself.
1 properties =
name: Bob
otherProperties: Citizen
2 actions =
name: Cat
links['self']: http://.../cat
links['create']: http://.../
3 hypermedia constraints: if we see properties for these we know we are dealing with a hypermedia API =
safety: S ([type=safe])
idempotence: I
mutability: M
presentation: P
make SIMPful apps! amundsen calls them ALPS. some properties in the response are rightfully about resources and all, but some are about protocol-level actions and protocol-level properties made explicit, discoverable and generically (not "continuously") integrated into a web (which is fundamentally distributed hypermedia application)
margaret runchey wanted to add gravitational signatures as metadata to all transactions and link relations, all indexed to a searchable system in her Model of Everything patent. that would require geometadata included in all responses from APIs. not just raw json, no matter how nested. but also: namespaces. we namespace JSON with colons and forward slashes, but what else can we represent in ASCII or plaintext as "link relation names"? can we make a game of "high low" with hyphens and underscores in link relations to represent "moves" in a game of tic tac toe? the actual baseboard would be the string value space of the [rel] however rendered on the page, but the game is fundamentally playable through curl requests but even still, through link relations inside of curl requests which make or may not be the same URL of that which hosts the resource. it could point anywhere, and the structure of the [rel] itself could be anyway, assuming our page has rendered whatever text node goes with it. it could mean anything to anyone, but it is published and structured. terms like:
directory/A
could be a [rel] but also:
Molecule-rolodex__header--active
why not? what could that HTTP request call? a complex component header that loads a search box that shouldn't be loaded until interacted with? shrug
what about [rel]=...:
2+2=4
i'd imagine example.org could actually host it. and it gives back a JSON with result, but also all sorts of metadata, maybe "next" link(s) for trying with minus or multiplication. obviously a history of past calculations should be given since most calculators offer up keys to recall the last entry. so the API could do a lot more than just give the result, but give a whole calculator interface, of affordances, to control it independently of the browser, just as an affordance that happens to be available at a URL
[1]: see IANA Link relations: 'Quasi-quotation is used to indicate (usually in more complex formulas) that the φ and "φ" in this sentence are related things, that one is the iteration of the other in a metalanguage.' [their emphasis] en.m.wikipedia.org/wiki/Quasi-quot...
Totally with you here!
Do you have any good resources on learning HATEOAS? I got the concept, but never understood how a concrete implementation should look like.
mike amundsen has a few concrete examples on his github: github.com/mamund (like he uses in his book Building Hypermedia APIs with HTML5 and Node — this < is on libgen dot rs — and more recently in Design and Build Great Web APIs), or amundsen's Hypermedia-Oriented Design paper: w3.org/2011/10/integration-worksho...
then there's hydra: hydra-cg.com/spec/latest/core/
another good follow on dev.to, who uses TypeScript: daniellittle.dev/practical-hyperme...
ofc, you'll run into many competing structures, Collection-JSON, HAL, Siren, etc., but lots of competition is exactly a vibrant scientific field, maybe... /me shrugs
Thanks!
honestly, i'd say it's less of a technical thing, tho tech is involved in highly unique and complicated ways... but one way i think about it is that it's just steganography, but in this case the "secret" message inside the message (or media) is as structured and complicated as a web application or component itself. in a sense, everything has a "Source" that can be viewed to reveal embedded links
but then, do knots not exist??
Hm, I looked into this and it seemed strange.
The "links" I understand, but they write about "actions" which seems very RPC-like to me 🤔
to an extent, yes, i think the "actions" decomposition of RPC (/customer/add) and OOP (/customer POST) and URL (/customer?add) all are options. but hypermedia is about putting links in the payload. if links are not in the response as a representation, however the URL looks doesnt so much matter. that comes down to CQRS, event sourcing, RPC, CRUD, etc. hypermedia wants to be in the response of the server, which entails that the response have links, not just properties. less or no nesting is a result of REST: fielding thinkings low nesting is good for distributed control, but hypermedia doesn't so much care as it is one way or another. but nested JSON or XML isn't HATEOAS, nor technically REST. nested queries neither, not even as request metadata. that's all one idea or another about databases and the hidden tax of Big O notation/syntax on queries as it relates to nesting. but hypermedia kicks in which not only is the response text, structured (markdowns), and includes image data (media) or video data (media), but as soon as HTTP protocol is introduced into the response itzelf, whatever it is. now we are not just sending messages, encrypted, secret, political, scientic, amorous, artistic, etc. but it isn't even just data, but it has aboutness: the quotation mark is now like a Quine quote[1]
those links are expressed as actions. sometimes they are CRUD, sometimes they are RPC, but they could be so much more. they could metadata about the API itself, as we see with HTTP OPTIONS0, they could be links to ledgers in cyberspace that are embedded inside other media, etc. that are inside torrent or magnet link file lists. the "read me" of the warez cracking tool could link to a wallet, or be the wallet to promote seeding the torrent and people can use wallet keys to unlock it to expend for their hosting for it in a signing party.
in any case, to an extend, yes it involves putting RPC style actions in a payload. that is exciting, like objects that could potentially operate each other. the link is there. all you have to do is query it, instead of find the result in the API and infer from result set or URL if you can POST there. does /user/ always entail i can create a user at that URI? will it be an affordance, a resource (AWS, k8s, etc. enter here with namespacing properties), a plain object or raw text data with no links?
you could have interfaces and menus as links, ofc. the entire game could be hyperlinks, but they would be on the DOM items themselves in the engine, discoverable properties and actions that other bots could cache and reason about, or that we could obviously automate too: we'd be automating affordances (configurations on HTML responses or JSON response that are properties for "safety", "mutability", "idempotence", "presentation") but all the properties of the hypermedia factors too. the hypermedia factors should be in responses in order for the API to be called RESTful, since they are evidence of its achieving Caching, Statelessness, etc. (its other constraints). so now our response not only needs structured text that may or may not be nested: it needs certain properties like [title], [method], action, [type], [rel], href, [name], src and possible [value]s. the response has these properties which give us confidence the API has a uniform interface, representation as a basis for resource manipulation, but are any of the values actually links? when they are values, and logics of the server support them, do they become RESTful. the links could point to anything: results in a google map, creation page for a payment, they could actually process as their methods if all the right conditions are in place for the link affordance to hold for that authorized key or user or session, etc. but more: [enctype] and [accept] are expected in the payload.
but more than this: [type] now includes semantics about the URL itself for values: semantic, safe, unsafe, idempotent.
so now affordances not only contain links to and about the nested or unnested architecture, which may or may not be actions, but we are including properties, metadata and navigational properties, links, but hypermedia controls which could be about the resource or the data or the object or the affordance itself.
etc, as seen above: slideshare.net/mobile/rnewton/rest...
make SIMPful apps! amundsen calls them ALPS. some properties in the response are rightfully about resources and all, but some are about protocol-level actions and protocol-level properties made explicit, discoverable and generically (not "continuously") integrated into a web (which is fundamentally distributed hypermedia application)
margaret runchey wanted to add gravitational signatures as metadata to all transactions and link relations, all indexed to a searchable system in her Model of Everything patent. that would require geometadata included in all responses from APIs. not just raw json, no matter how nested. but also: namespaces. we namespace JSON with colons and forward slashes, but what else can we represent in ASCII or plaintext as "link relation names"? can we make a game of "high low" with hyphens and underscores in link relations to represent "moves" in a game of tic tac toe? the actual baseboard would be the string value space of the [rel] however rendered on the page, but the game is fundamentally playable through
curlrequests but even still, through link relations inside ofcurlrequests which make or may not be the same URL of that which hosts the resource. it could point anywhere, and the structure of the [rel] itself could be anyway, assuming our page has rendered whatever text node goes with it. it could mean anything to anyone, but it is published and structured. terms like:could be a [rel] but also:
why not? what could that HTTP request call? a complex component header that loads a search box that shouldn't be loaded until interacted with? shrug
what about [rel]=...:
i'd imagine example.org could actually host it. and it gives back a JSON with result, but also all sorts of metadata, maybe "next" link(s) for trying with minus or multiplication. obviously a history of past calculations should be given since most calculators offer up keys to recall the last entry. so the API could do a lot more than just give the result, but give a whole calculator interface, of affordances, to control it independently of the browser, just as an affordance that happens to be available at a URL
[1]: see IANA Link relations: 'Quasi-quotation is used to indicate (usually in more complex formulas) that the φ and "φ" in this sentence are related things, that one is the iteration of the other in a metalanguage.' [their emphasis] en.m.wikipedia.org/wiki/Quasi-quot...
added a reply and updated 😌😣