Why there will never be a _ref at the base of an object.

[TakenPilot]

For whenever this is brought up again, these are the reasons why there will never be a _ref at the base of any object within this particular project. This post contains logic that will hopefully be referred to from other issues to avoid repeating the same logic in other threads.

For example, we can return something like this:

{
  "a": {
    "_ref": "<someone else's resource id>" 
  }
}

When that object is composed, we will recursively add the data from _ref to the object in a. However, we shouldn't do this:

{
  "_ref": "<my own resource id>" 
}

1. The meaning of the word reference is "something that refers" and I am very hesitant to give the word special meaning for our particular project. That is, it shouldn't suddenly change from representing "that guy over there" to "who I am" because of its position in an object tree.

Reference:
a : allusion, mention
b : something (as a sign or indication) that refers a reader or consulter to another source of information (as a book or passage)
c : consultation of sources of information

2. In a RESTful API, GET <--> PUT is supposed to be commutative in that putting something somewhere should mean that getting the exact same uri should give the exact thing you put there, and vice versa. There are multiple places you could get the same information from, and assigning a ref into the data means you can't save to multiple places without modifying the data each time (i.e., versioning, publishing, etc.).

3. Having a _ref means that you are pointing somewhere else, and that anything in that ref object means that it is someone else's data. Having a _ref at the base is implying that the entire object is someone else's data. Unless you're trying to create an exception?

4. Having a _ref at the base of an object means that you can easily PUT an object with a base-level _ref to a uri that doesn't match; we often PUT to multiple places because of publishing and versioning, and having the uri in the data means we have to edit the data each time we were to do that. Performing a simple diff between objects becomes a multiple step process. Having an object at a certain uri with a base _ref pointing to a different uri sounds like a debugging nightmare.

5. Having a ref at the base of an object means that all of the code that does recursion on our objects will have to be rewritten. This includes how we do composition, how we create new pages, and how we publish data. It would have to be rewriten to ignore the first level of data and then start the recursion, which considering that most of our objects are only a single level or two levels deep, would do terrible things to our performance. For scale, that's about 60% of byline-core's codebase.

---

These arguments were originally posted here: clay/clay-kiln#89

This Issue is referenced in our routing documentation.

[nelsonpecora]

As an addendum, the _self exposed in HTML requests will always be the URI of the thing being requested. This means a few things:

• GET /pages/:id.html will expose the page's URI
• GET /components/:name/instances/:id.html wil expose the component's URI

This is the reason why the data-uri in root elements of our layouts is the page URI when requesting a composed page and the layout component's URI when requesting the layout itself.