listen, web developer!
Tags: hypermedia, ddd, webdev, rest
Published: 2020-10-11 16:43:27

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

![think domain driven hypermedia oriented design!](https://dev-to-uploads.s3.amazonaws.com/i/yzbxiixiqrq2jow0pkub.jpg)

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:

```json
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:

```json
{
  "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 `Request`s like `GET`, `PUT`, etc. and resolve into HTTP Status `Response`s (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)`

```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:

```json
      ...
      "rel": "create",
      ...
```

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

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

but really, it could be rendered anywhere:

```html
<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:

```markdown
  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_token`s, 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)