[mdx] returning the "all entities" aggregate

[Ian Young]

On 3 Sep 2014, at 19:20, Tom Scavo <trscavo at gmail.com> wrote:

> I'm looking at this semi-documented issue:
> 
> https://github.com/iay/md-query/issues/11
> 
> The issue seems to be characterized as an implementation issue but I'm
> more interested in how this will be incorporated into the spec. Would
> someone care to speculate as to the wording that might be used?

My intention was to have some wording which simply listed that endpoint (.../entities) and said that it returned metadata for all available entities. There would need to be a fair bit of rewording to get to that, though, because I'd want to refactor some of the current text about the meaning of the base URL which to my mind currently draws the line in the wrong place (that section about conditionally adding a '/' is a symptom).

So I don't have precise wording available, but the idea (that .../entities should return the aggregate from which each .../entities/ID URL selected) isn't particularly complex. It's very common in RESTian APIs to order things hierarchically in this way, and that was the original idea: /entities is the aggregate, /entities/ID are the individual entities or other selections.

> We are bringing up an mdq-server as we speak but I don't really want
> to equate the "all entities" aggregate with the base URL since users
> will end up pulling back the aggregate quite by accident, and such a
> mistake is not without consequences since obviously the aggregate can
> be quite large.

I'm not sure how a user would pull the aggregate by accident, except perhaps by using a browser. That particular case is easy to cover off in the implementation, I think. My current implementation already uses content type negotiation to deliver a different (human-readable) document to a browser than from a direct HTTP query, and the HTML template for /entities doesn't need to be the same as the template for /entities/ID. At the moment they are both the same, of course, see

https://github.com/iay/mdq-server/blob/master/src/main/java/uk/org/iay/mdq/server/EntitiesController.java

https://github.com/iay/mdq-server/blob/master/src/main/resources/templates/queryResult.tpl

> Indeed, in the end I would prefer not to serve *any* aggregates from
> the mdq-server since that drastically alters the required capabilities
> of the server. A server that serves only per-entity metadata would
> seem to have very modest server requirements, I think. (I have no data
> to back this up, I'm just claiming something that appears to me to be
> obvious.)
> 
> So, if you want to map the base URL to the "all entities" aggregate,
> that's fine with me as long as any given deployment is free to return
> a 404 response. Better yet, I would rather return a 400 response and
> define a tag that implies "all entities," but in any case, a
> deployment should not be required to support it.

If you mean define an identifier to represent "all entities", I guess we could do that, and just pick one that is likely to be unused in an actual entity identifier: we've already effectively sold that pass with "{sha1}" although if we do the refactoring I suggested last week then that is SAML only and this would reintroduce a special case into the protocol document. I think it's (much) less elegant than the original intention, though, just to sidestep serving something you (let's assume for good reason even if it's arguable in any particular case) don't want to serve.

If this is a real concern that we want to address, I'd probably prefer to come up with some wording to say "and the server can blow off any requests it likes for policy reasons using HTTP code XXX". There's probably an existing code that does what we want, in fact.

	-- Ian



-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 5943 bytes
Desc: not available
URL: <http://lists.iay.org.uk/pipermail/mdx-iay.org.uk/attachments/20140903/570de6dc/attachment.bin>