Re: Commentary on the "protocol" draft

Really, there's only Roy Fielding's dissertation that's "conclusive":
http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

REST is an architectural style, not a protocol, etc. So there's no real
"spec" (beyond the dissertation), though there has been mountains of
writing, coding, conferencing, discussing, etc, on the topic.

The vast majority of APIs (with or without a claim at being "RESTful") are
not. LDP, AtomPub, and a handful of others come as close as anyone (because
hypermedia). There's also been a strong current away from the term "REST"
because of it's frequent misapplication. The replacement term is
"Hypermedia API" which encompasses the core concept (from the dissertation)
of "Hypermedia as the engine of application state" or, if you like
acronyms, HATEOAS:
http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

REST (because it's an architectural *style*) can be applied to other
protocols beyond HTTP. HTTP just happens to be the one Roy used to describe
it, so people get them tangled up. But, as Rob mentioned, there's no reason
to call that out in the current protocol proposal as it's only using HTTP.

Hopefully that's helpful. :)

Let me know if you have other questions off list, or in the #rest channel
on irc.freenode.net if you're into IRC, so we can return this list to it's
regularly scheduled programming. ;)

Cheers,
Benjamin

On Thu, Feb 5, 2015 at 10:56 AM, Denenberg, Ray <rden@loc.gov> wrote:

> Regarding REST.  Is there even any normative REST spec? If so, I can’t
> find it.  How then do other (normative) specs call out REST?
>
>
>
> Ray
>
>
>
> *From:* Robert Sanderson [mailto:azaroth42@gmail.com]
> *Sent:* Thursday, February 05, 2015 10:31 AM
> *To:* public-annotation@w3.org
> *Cc:* Web Annotation
> *Subject:* Re: Commentary on the "protocol" draft
>
>
>
>
>
> Thanks Nick!  Responses inline below.
>
>
>
> On Wed, Feb 4, 2015 at 9:45 AM, Nick Stenning <nick@whiteink.com> wrote:
>
> There are a couple of relatively minor questions I have, such as:
> - When you say "the REST best practice guidelines" -- are you
> referring to a specific document?
>
>
>
> No, so that's probably over-worded.  I just mean REST in general, rather
> than some arbitrary pattern.
>
> Will change the wording there.
>
>
>
>
>
> - You say "interactions are designed to take place over HTTP, but the
> design should not prevent implementations that carry the transactions
> over other protocols". Perhaps I've misunderstood what you mean, but
> this seems to be a design constraint that is at odds with REST. How can
> a protocol which specifies verbs and status codes be implementable out
> of an HTTP context? My inclination would be to remove this altogether
> and be clear that we are designing an HTTP protocol for annotation.
>
>
>
> +1  The principle came from a requirement I've heard in the past that
> interactions should be able to take place over a persistent stream like
> websockets or similar.  Agree, now that I've actually put some words down,
> that it's not feasible at the same time as using LDP without some abstract
> API spec that gets instantiated multiple ways. Which seems like overkill.
>
> If there's interest in stream based protocols, I think we could have a
> second protocol document down the line that's hopefully just how to
> translate into a message.
>
>
>
>
>
> - As specified, a container representation MUST contain a list of
> contained annotations. This seems increasingly impractical as a
> container grows in size, and doesn't seem to admit much subtlety around
> authorisation and access controls. Is this part of LDP? If so perhaps
> the container model doesn't fit here -- would a conforming
> implementation on top of the Hypothes.is data store have to include tens
> of thousands of annotation URIs in the top-level resource body?
>
>
>
> Yes, it is a requirement we've inherited.  There's a few mitigating
> factors:
>
>
>
> * There's the notion of paging in LDP: http://www.w3.org/TR/ldp-paging/
>
>    This would let the response be split up into chunks as needed.
>
>
>
> * Only the URI needs to be transferred, not the entire annotation. The URI
> can be relative, so the JSON-LD in example 2 (
> http://w3c.github.io/web-annotation/protocol/wd/#containers-for-annotations)
> with 10,000 annoX strings is what the response would look like.
>
>
>
> *  The requirement comes from discovery, as LDP doesn't have any search
> capabilities inherently, so the list of contained resources is to let a
> harvesting follow-your-nose approach work.  Other than for discovery of
> annotation URIs, I'm not sure why you'd ever retrieve the container
> description.
>
>
>
> * There could be many such containers to divide up the list, each with
> their own authorization/authentication controls.  Auth isn't currently
> specified in LDP but is on the roadmap for future work.
>
>
>
> Overall I agree it's not ideal, but I don't think it's a significant
> barrier to entry either?
>
>
>
>
>
> I also have one overall concern, which is that the design you've
> proposed seems like a compromise between two rather different groups of
> users, which by virtue of being a compromise doesn't really satisfy
> either of them.
>
> My postulate is that there are two broad classes of people who need
> annotation protocols:
> (1) Bulk data stores and archival services
> (2) User-facing clients
>
>
>
>
>
> Agreed. I wanted to map directly into LDP with as few additional
> requirements / constraints as possible in the first cut at this.  The
> result is something that seems like it should work but isn't optimized for
> any particular scenario. (premature optimization and all that)
>
>
>
>
>
> Bulk clients [...] will be stymied by:
> - requirement to list all annotations in a container
>
>
>
> Not sure that the client would ever need to retrieve the container
> description.
>
>
>
> - no bulk retrieval or submission
>
>
>
> Agreed. Bulk retrieval seems like a search operation, bulk submission OTOH
> is harder.
>
>
>
>  - no easy way to retrieve updates since $TIMESTAMP (q.v. SLEEP [1])
>
>
>
> Harvesting by time also seems like search.
>
>
>
>
>
> User-facing clients [...] won't like:
> - no normative specification of how to search for annotations relevant to
> the current page
>
>
>
> Agreed.
>
>
>
> - LD Patch
>
> - distinction between PUT and PATCH
>
>
>
> Yep. Theres also the JSON PATCH format (RFC 6902:
> https://tools.ietf.org/html/rfc6902) that we could adopt as we can
> mandate the structure of the JSON via the JSON-LD context and serialization
> spec.  OTOH, patching is just a hard problem, particularly so with graphs,
> and doubled by the existence of blank nodes where the id isn't consistent.
>
>
>
>
>
> - no guidance on error handling
>
>
>
> +1, to be discussed.
>
>
>
> - conneg
>
>
>
> I'm not a big fan of content negotiation either, TBH, but it's part of the
> web architecture.  This is one I think we can plaster over a little by
> setting the defaults sensibly so that conneg doesn't really need to be done
> for basic usage by browser based clients.
>
>
>
>
>
> Overall, I think it might worth thinking about whether splitting these
> two use cases would allow us to focus on:
> - interoperability and bulk data flows for group (1)
> - simple data formats, low implementation overhead and document-oriented
> workflows for group (2)
>
>
>
> I think that would be very valuable as a way to make progress. There'll
> need to be some compromises between them as we don't want two totally
> separate protocols, but finding the right ones to make seems like our task
> in this WG :)
>
>
>
> Rob
>
>
>
> --
>
> Rob Sanderson
>
> Information Standards Advocate
>
> Digital Library Systems and Services
>
> Stanford, CA 94305
>