listen, web developer!

if the developer is not putting links in their JSON or XML response, they are not doing web development! it's that simple!

one philosophical decision, or perhaps ontological commitment, implicit to the definition of the web is that links are distributed; the web is fundamentally a distributed hypermedia application. it runs on port 80. links are distributed throughout its territory, notably inside of hypermedia. often, most often, hypermedia is served at some URL, like .../kitten.jpg (notice the file extension). why not: .../kitten/? well, usually because achieving this technically can be politically and technically difficult within an organization. nevertheless, it is obtainable and consistent with the terms of semantic web.

your JSON response could also be served as .../kitten.json but you usually don't, it's usually prefigured into an API somewhere; let alone adding links is a non-trivial task within maybe API frameworks, like even ExpressJS, HapiJS, LoopBack, and so on. so usually the prototypical example response is something like this:

GET ./kitten.jpg
<some jpeg that is text-like>

and:

GET ./kitten/
{
  "name": "morton"
}

but all hypermedia requires is embedding links in the HTTP response payload (hypermedia control can be extricated from REST, but that leaves us to wonder: what was the point of REST? well, it's first use-case is distributed control through hypermedia!), the entire raison d'etre of ReST is the following:

GET ./kitten.jpg
  <ul>
    <li><a rel="link-relation-type" href="/#state-machine-route?continuation-token={%= cont_token %}">State Machine Route</a></li>
  </ul>
  ...
  rest of the jpeg

and for application/json... subtypes:

{
  "name": "morton",
  "links": [
    {
      "rel": "{% state || 'link-relation-type' %}",
      "href": "{macroForBaseUrlReplacement}/#state-machine-route?continuation-token={%= cont_token %}"
    }
  ]
}

so now the client can navigation and discover "links" conceived through the [rel] attribute. think of baruch spinoza's "order and connection" of ideas and things: these [rel]s are the events, whether relations or decisions, of the state machine, expressed in HTTP Verb Requests like GET, PUT, etc. and resolve into HTTP Status Responses (if you're familiar with Express, etc.). one could say that POST, e.g., is not a "relation" but rather a decision, so it has no place in the list of [rel]s. i would argument that an alias can be constructed that is a link relation that maps to all the HTTP Verbs. so we get:

GET /kitten.jpg (or /kitten/; or /kitten.json)

{
  "links": [
    {
      "href": "http://example.com",
      "rel": "create",
      "tags": "...",
      "method": "POST",
      "fields": [
        "..."
      ]
    }
  ]
}

we get an HTTP 200. one question is what that response should look like for a 200 versus, say, a 201 given we're looking for a "kitten". which links should be available, and why? is the kitten in a grocery store? is it being purchased in a shop? what is the background of the resource model? this will determine the "syntax of the affordance" in the resource served. the client will do "the right thing", presumably, when it discovers the link and integrates its business into the grander schema of the internet of things.

but what other schemas are there? one line in particular is relevant:

      ...
      "rel": "create",
      ...

in the HTML into which it is given, it will likely be rendered so:

  <a rel="create" ...>...</a>

but really, it could be rendered anywhere:

<div uri:header="create" ...>
  ...
</div>

in which case, there will be JavaScript that is doing something Smart, Fun, Sexy and Cool (and presumably Perceivably, Operably, Understandably and Robustly); DOM updates, traversals and manipulations and all.

however, these are naming opportunities we're overlooking, for "create" could be anything, really:

  open
  version
  v1
  create.v1
  create:partOf
  go/north
  play
  replay
  update
  continue
  next
  continuation
  narration
  action
  potentialAction
  tradeAction
  O-panel__header--active
  rgb(--(...),--var(...),99)
  library/**/shelves/createdAd
  ∀x(Fx&¬G)
  m/5nYUWL0hAWy0Hw4T33XpnTnf0WQ7eOgCBQJUpMZs8=
  127.0.0.1/login

you get the idea (link relations exist: https://www.iana.org/assignments/link-relations/link-relations.xhtml, http://microformats.org/wiki/existing-rel-values, https://schema.org/SoftwareApplication): many different ways to express the interstructural matters of architectural style in a semiotic plane of consistency.

margaret runchey envisions a similar idea back in 2001 or earlier, of link relations as transaction identifiers owning people as data, as it were, as such "establishing a symbolic identity by formalizing referential relationship between a resource event (you) and an identifier": https://patents.google.com/patent/US7774388B1/en

it's data that, at the most, owns other data. which is presupposed as sensible and true in most Western ontologies, to some extent: a dog owns it own hair, surely.

"... there is also a built-in internal link through Unitary Integrated Ontology to predicate logic constructions. ... UR-URL ..." (Ibid.) and so on.

at any rate, what DDD does in infrastructure, Amundsen does in "data.js" in his starter, or at least explicitly: infra incorporates domains, so models are given living data, their data types are wedded to repositories, which i believe should exist in infrastructure at its base. the modules aspect, in interfaces like HTTP, is where DDD and HOD (hypermedia-oriented design) make first contact.

i'm reminded of a question in the philosophy corridors of w3c: "Isn’t there a need for cacheing the results of the various reasoners in a FOL form?" (https://www.w3.org/community/philoweb/2014/01/15/syllogism/) it haunts me today. could a state machine use such a "memory" of reasoners housed in the web (add "memories", but also "apologies" and "guesses" (see CALM)? like an archive.org of publically, biblically accessible links to results of all propositional knowledge. what if we switch our conceptual focus to probabilistic knowledge (Sarah Moss): how will we achieve new results for MCMC algorithms claiming mathematical forms of novel inner structural and hyperdimensional complexity. could such an engine find your car keys? probably. it'd be a link in a Resource Directory (CoAP/CoRE) in your programmable home. in any event, it'll be programmable through semantic web, namely timbl's invention: Linked Data. if it is raining and the key is outside and Smith has ten coins in his pocket, etc. (see Gettier) so perhaps these reasoners would fumble, in which case we introduce the concept of "anaphora"; Smith and Jones get their own indexicalized non-representational pronoun meaning tags "he_sub(jones)". the Gettier problem vanished in our syntax, since intuitively we do not think that Smith thinks he_sub(smith) will get the job. why should Gettier get to couch in a conversational or casual pronoun embedding rule that loses, conveniently, tracking of pronoun veridicality exactly necessary for his argument to be "successful", when Sebastian Roedl formalizes explicitly pronoun use in symbolic relations structured inherently to joint spontaneous knowledge in his paper "You and I"? is it something we commonly "translate away" when converting sentences like "S has ten coins in their pocket"? does the gettier problem hold if jones and smith are a-gender? probably. if they are robots or epistemic agents or things of any sort for all sorts of language, in every language, because the logic rules gettier mentions and the one i am calling out here that he couches in are always processed one way within a socio-cultural mileu? probably not. but i digress.

if the web is a "virtual state machine" as Roy Fielding suggests, try yEd2Kingly: https://github.com/brucou/yed2Kingly#examples to build out your RESTful hypermedia systems according to Mike Amundsen's DARRT: https://github.com/mamund/api-starter/blob/master/darrt/. put hypermedia controls in your images and serve Winamp media players or cryptowallets inside them. give them voice commands, via DOM development, so now images can be served on simple web hosts and intercommunicate with APIs that respond to those voice commands over whatever host device is serving the media, given whatever host capabilities that media is reactively written to support. now the media can crawl about, through people sharing it, can report back interactions to a server, true, but if it has a cryptowallet to which it is passing continuation_tokens, then the requestions can be made transactions with eventual consistency and disorderly programming via (Bloom/Bud and reasoning according to CALM: https://speakerdeck.com/jhellerstein/the-calm-theorem-positive-directions-for-distributed-computing)

Comments

[K]

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.

[⚫️ nothingness negates itself]

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

[K]

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 🤔

[⚫️ nothingness negates itself]

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

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 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...

[⚫️ nothingness negates itself]

added a reply and updated 😌😣

[K]

Thanks!

[⚫️ nothingness negates itself]

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??