[mdx] returning the "all entities" aggregate

[Tom Scavo]

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?

> 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.

I don't see any normative language in there but I'm content to "wait
and see" :-)

> 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.

> 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?

> 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.

Tom