oEmbed for Pages

[knowtheory]

• add resource location (a fixed URL) for individual pages
• add support for recognizing page resources in oEmbed action/lib.

[reefdog]

So, fixed URL for pages. My initial recommendation would be:

• https://www.documentcloud.org/documents/282753-lefler-thesis/pages/1.html

But our existing formats for static page text and image assets are:

• https://www.documentcloud.org/documents/282753/pages/lefler-thesis-p1.txt
• https://assets.documentcloud.org/documents/282753/pages/lefler-thesis-p1-{size}.gif

At first this appeared to be sheer lunacy. Then I realized it's probably to ensure the downloaded filename is sensible (lefler-thesis-p1.txt makes far more sense in a Downloads folder than 1.txt), and I liked it.

So do we:

1. Stay consistent with the existing format for static page assets: Consistency makes our lives and the lives of our third-party devs easier
2. Make this URL sensible on its own, since it's under different requirements: Sensible URL that doesn't require knowledge of the "static asset" context

My vote is for №2.

[reefdog]

Just two hours to pull a 180.

I don't expect us to widely advertise page URLs, which makes consistency even more important. (The most common "page URL" will likely be the page anchor on the document page, ala https://www.documentcloud.org/documents/282753-lefler-thesis.html#document/p1, which can't serve as the page-specific oEmbed endpoint and thus will be coerced into a page resource URL by things like the WordPress plugin.)

So, changing my vote to №1.

[knowtheory]

Yeah, okay so there's a lot to unpack here. We're caught between 3 or 4 different systems that are colliding.

1. platform resource url structure (we're supposed to be using fully slugged ids, e.g. /\d+-[0-9a-z-]+/)
2. s3 resource url structure (which is just numeric id as a namespace for other files)
3. The DocumentViewer uses # anchors to provide linkable modes in the app e.g. #document/p4, #document/p13/a80993, #text/p13 and most notably #pages.
4. the platform again where it maps resources directly from documentcloud.org to s3.
5. The fact that we should probably transitioning from anchor hashes to pushState everywhere.

Okay, so with that madness as context, we should do some unification and moving towards a consistent URL scheme where we can.

My initial thought was that a document is already a collection/list for pages (and to use /documents/1234-some-slug/p1.json)... but essentially all of the systems listed above argue against that (even the DocumentViewer).

So instead i'd rather ask what can we lay out that 1) most closely resembles a system that we would design today which would feed a push state enabled viewer, and 2) allows us to continue to support applications and other tools that are pulling from existing urls & paths.

[knowtheory]

Okay, so what are our possibilities?

1. /documents/1234-some-slug/pages/1.json
2. /documents/1234-some-slug/pages/p1.json
3. /documents/1234-some-slug/pages/some-slug-p1.json
4. /documents/1234/pages/some-slug-p1.json

[reefdog]

I'm so happy that you're on board with unmaddening the madness, and agree with the direction of this conversation. There are several dimensions to consider, hopefully I won't make a mess of them.

oEmbed discovery

We all know this, but for posterity, here's how oEmbed works: an oEmbed consumer (e.g., WordPress) says "I have this URL (e.g.) and I need to know how to embed it; I'm going to fetch that URL and look for a <link rel="alternate" type="application/json+oembed" href="…"> tag in the header whose href contains a URL (e.g.) that gives me the proper embed code."

Any resource we want to be oEmbeddable needs a URL that returns an HTML page with a resource-specific link tag. (Keep reading.)

Canon and context

There are two ways to present a document sub-resource (page/note):

1. In the context of the parent document (aka page anchor)
2. Stripped down on its own HTML page

№1 is required. If pushState lets us recompose the oEmbed link tag without a page reload, then №2 is optional; if not, it's also required.

Given that setup…

1. Does pushState let us recompose the oEmbed link tag without a page reload?
   1. If yes, then do we even want the platform to host stripped-down sub-resource HTML pages?
      1. If yes, then we need separate URLs for canon and context, and I'd suggest making them nearly identical: /documents/1234-some-slug/pages/1 and /documents/1234-some-slug#pages/1
      2. If no (recommended), the canonical URL for a sub-resource would be a pushState-based URL like /documents/1234-some-slug/pages/1 that acts like a page anchor
      3. Either way, the JSON endpoints would be /documents/1234-some-slug/pages/1.json and /documents/1234-some-slug/annotations/456.json
   2. If no, then then 1.i.b. above applies
2. Format placement in a pushState-based context URL is weird: /documents/1234-some-slug.html/pages/1 (gross) or /documents/1234-some-slug/pages/1.html (deceptive). Is it practical to ditch .html and assume HTML when no format is specified?
3. Whatever we change, we need a redirect path for existing URLs. No existing URLs should break.
4. Static asset URLs don't need to change. These are invisible to users (except API users) and should be machine-optimized.

[knowtheory]

re point 2:

That's not deceptive. You're asking for a link to a particular page/resource. If they were to scroll to another page, the pushState URL should update. The one weird part is that once you're down in a page view... how do you get back up to the collection view. And yes i think .html should be specified.

[reefdog]

(Gonna regurgitate our phone conversation here for posterity.)

What we're talking about with /documents/123-slug/pages/1.html isn't actually page anchor behavior, even if that's how it's expressed in the current viewer; it's actually state behavior. "Give me document 123 in the state of page 1." Given that context, I'm more comfortable with format placement.

@knowtheory and I really like this idea:

• /documents/123-slug.{format}
• /documents/123-slug/pages/456.{format}
• /documents/123-slug/annotations/789.{format}

The viewer would be pushState-enabled. The sub-resource links open the document, lightboxed in the state of the specified sub-resource, ala how notes are now. (We're using "lightboxed" simply for conversation; please ignore term baggage.) Rails renders the page with the oEmbed link composed for the specific sub-resource requested; I say changes to the page state should dynamically update this oEmbed link tag, @knowtheory says that'll be wasted effort given how immaterial it is to actual oEmbed consumers. Punting on that decision until we're actually implementing pushState.

[knowtheory]

yeah... so actually the way i'd frame this is that a resource is basically a request for some data by a user. We also happen to ship along with that data an app that lets the user view the data.

So the fact that the document resource and the page resource use the same viewer is sort of incidental. But the type of resource that's being requested lets the app know what state we intend the user to see.