couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Benjamin Young (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (COUCHDB-2052) Add API for discovering feature availability
Date Fri, 07 Feb 2014 15:20:24 GMT

    [ 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)

Mime
View raw message