[Pulp-list] schedule sub-collections

[Nick Coghlan]

On 09/11/2012 03:13 PM, Jason Connor wrote:
> Been doing a little thinking, my current model for schedule sub-collections kinda sucks.
> 
> It's as follows (for the schedule REST APIs defined so far):
> 
> /v2/repositories/<repo id>/importers/<importer id>/sync_schedules/
> /v2/repositories/<repo id>/distributors/<distributor id>/publish_schedules/
> /v2/consumers/<consumer id>/unit_install_schedules/
> 
> I think the repo importers and distributors sub-collections kinda tripped me up. I think the following is a better (more RESTful?) implementation, and I'm looking for feedback (thumbs up/thumbs down kinda thing)
> 
> /v2/repositories/<repo id>/importers/<importer id>/schedules/sync/
> /v2/repositories/<repo id>/distributors/<distributor id>/schedules/publish/
> /v2/consumers/<consumer id>/schedules/unit_install/
> /v2/consumers/<consumer id>/schedules/unit_update/
> /v2/consumers/<consumer id>/schedules/unit_uninstall/

While I think that's a definite improvement, those first two URLs are
also getting rather deeply nested for a REST API reference. I'd be more
inclined to flatten them out a bit by hooking them directly to the
repository:

/v2/repositories/<repo id>/schedules/sync/
/v2/repositories/<repo id>/schedules/publish/

This also better matches the existing "actions" API, which lives at the
repo level, not the importer/distributor level.

And so, on that note, have you considered simply creating a parallel
"schedules" tree for each existing "actions" subtree? That would give an
API like:

/v2/repositories/<repo id>/schedules/sync/
/v2/repositories/<repo id>/schedules/publish/
/v2/consumers/<consumer id>/schedules/content/install/
/v2/consumers/<consumer id>/schedules/content/update/
/v2/consumers/<consumer id>/schedules/content/uninstall/

In the spirit of REST navigability, the returned JSON documents for each
schedule entry could even include the equivalent URL and request body
that could be POSTed to achieve the same effect as the scheduled event.

Side note: it would be handy if the REST API docs included a "URL map"
for the full API. Something similar to
http://pulpdist.readthedocs.org/en/latest/webapp.html#rest-api, but
autogenerated from the existing docs. This may require more
sophisticated Sphinx-fu than is used in the current docs, though :(

Cheers,
Nick.

-- 
Nick Coghlan
Red Hat Infrastructure Engineering & Development, Brisbane