[mdx] returning the "all entities" aggregate

[Ian Young]

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

> On Wed, Sep 3, 2014 at 3:04 PM, Ian Young <ian at iay.org.uk> wrote:
>> 
>> On 3 Sep 2014, at 19:20, Tom Scavo <trscavo at gmail.com> wrote:
>> 
>> 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).
> 
> Yes, that slash is a bugaboo. Should the spec insist on the base URL
> *not* ending with a slash?

I had a draft of the changed text, but I've lost it. I think I ended up finding that things were cleanest if you say the opposite: the base URL MUST end with a slash, and then the endpoints are just below that as "entities", "entities/ID" etc.

One way or another, though, lifting the normalisation of the "/" part of the path up makes thing easier to understand.

>> 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.
> 
> Yes, but any such API will also have a very elaborate paging mechanism
> so I'm not sure the analogy is sound.

True, what we have is definitely more "inspired by REST" than strictly RESTian, at least by some definitions of the latter. I was commenting more on the original concept than on the details.

>> 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.
> 
> That's a good point, I hadn't thought about that, and indeed, that
> mostly nullifies my concern. However, I remember when I first saw your
> implementation behave that way...I was quite surprised. Perhaps this
> could be discussed in the spec somehow, as implementation guidance
> perhaps?

I'd welcome some specific wording we can start to hash around. Meanwhile, I think I will go "just do that" with the mdq-server implementation and see what it looks like. Frankly, I don't particularly want to be serving 20MB HTML documents off my home ADSL network either and this would be a good way to put the kibosh on that...

>> 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.
> 
> That would be fine, thanks.

Cool.

	-- 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/de23fbb3/attachment-0001.bin>