[
https://issues.apache.org/jira/browse/COUCHDB-2052?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13894623#comment-13894623
]
Benjamin Young commented on COUCHDB-2052:
-----------------------------------------
[~klaus_trainer] great thread! Good thoughts in there that do match this
conversation closely.
[~snej] you're absolutely correct that just exposing URL endpoint existence is
not enough. Document types, capability's (thanks, Klaus!), etc. have to be
identifiable and understandable (or ignored).
jsonapi.com came up in the thread Klaus linked too, and it's very much like the
other JSON-based Hypermedia API options mentioned above--it's a small group of
inventors and all these folks cross paths often. :)
One thing that a good Hypermedia API provides is "affordances":
bq. ...the term affordance refers to the perceived and actual properties of the
thing, primarily those fundamental properties that determine just how the thing
could possibly be used. (pg 9)
??The (Design|Psychology) of Everyday Things (Norman, 1988)??
Cribbed that quote from [this great blog
post|http://www.amundsen.com/blog/archives/1109] on the topic by Mike Amundsen
who also wrote [Hypermedia-Oriented
Design|http://www.w3.org/2011/10/integration-workshop/p/hypermedia-oriented-design.pdf].
Affordances is a broad concept that encompasses more than just URL exposure. It
can (and should) include defining document types (as the above Hypermedia API
options have done...and registered them with IANA, so others can find them).
[~snej] in the case of the channels document additions, those documents would
have their "magic" defined in a media (formerly MIME) type named something like
{{application/vnd.couchbase.channel+json}}. The endpoints that traffic in those
documents could then handle either respond/accept raw JSON
({{application/json}}) or ({{application/vnd.couchbase.channel+json}}). Both
are "just" JSON, but in the later format some features are assumed, required,
expected.
JSON Schema's (or similar) could be provided and referenced (where
appropriate/expected depending on the format...and of course with human-focused
documentation), so validating, editing, and processing these JSON-based media
types would be a "known quantity" and not anybody's guess what "channel" or
"_rev" for that matter might mean, do, etc.
In the end, it's quite similar to the CAPAB option mentioned in the thread
Klaus linked to. Just with the addition of URL's for all those CAPAB's, so they
can be dereferenced, understood, and used more easily and more globally.
That's the idea anyway. :)
> Add API for discovering feature availability
> --------------------------------------------
>
> Key: COUCHDB-2052
> URL: https://issues.apache.org/jira/browse/COUCHDB-2052
> Project: CouchDB
> Issue Type: Improvement
> Security Level: public(Regular issues)
> Components: HTTP Interface
> Reporter: Jens Alfke
>
> I propose adding to the response of "GET /" a property called "features" or
> "extensions" whose value is an array of strings, each string being an
> agreed-upon identifier of a specific optional feature. For example:
> {"couchdb": "welcome", "features": ["_bulk_get", "persona"]}, "vendor":
> …
> Rationale:
> Features are being added to CouchDB over time, plug-ins may add features, and
> there are compatible servers that may have nonstandard features (like
> _bulk_get). But there isn't a clear way for a client (which might be another
> server's replicator) to determine what features a server has. Currently a
> client looking at the response of a GET / has to figure out what server and
> version thereof it's talking to, and then has to consult hardcoded knowledge
> that version X of server Y supports feature Z.
> (True, you can often get away without needing to check, by assuming a feature
> exists but falling back to standard behavior if you get an error. But not all
> features may be so easy to detect — the behavior of an unaware server might
> be to ignore the feature and do the wrong thing, rather than returning an
> error — and anyway this adds extra round-trips that slow down the operation.)
--
This message was sent by Atlassian JIRA
(v6.1.5#6160)
