Github user ahgittin commented on the issue:
https://github.com/apache/brooklyn-server/pull/810
As per ML:
Aled, Thomas, Mark - thanks for the good feedback.
All - There are some good suggestions which I agree deserve discussion.
Specific points.
(1) Should /types and /bundles be top-level or under a /catalog prefix ?
Thomas suggested the latter which also fits. My reason for doing top-level is
simply that most REST APIs these days seem to have more top-level resources.
/catalog is not necessary and in some ways it's cleaner having separate
endpoints. On the other hand the /catalog prefix is nice to orient consumers,
as Aled says: `bundles` and `types` on their own aren't as self-evident. And
it means we could continue to have `POST /catalog` as the main way to install.
(2) Should we deprecate `/catalog` ? Thomas suggests maybe not yet. I
think we should as equivalent functionality and more is available at the new
endpoints. (Though if we go with (1), obviously we wouldn't deprecate the
whole endpoint, just the old calls.). Also worth noting: I don't think we
should remove the deprecated endpoint anytime soon however.
(3) Should we switch to /v2 ? Aled has suggested we do as the generic
`types` support is a significant shift from the old more restrictive `catalog`.
I don't think we should yet, however: I'd prefer to make that move when we
are ready to remove all old endpoints so v2 is clutter-free. To the extent v2
can look like a subset of v1 we make life easier for users and ourselves. Also
there is significant work to add a /v2 endpoint and I don't think there is
benefit yet to justify this work.
(4) Should `/subtypes` be an endpoint peer of `/types` ? It has been noted
the same functionality as `/subtypes/entity` could be done with
`/types?super=entity` (with appropriate query paramter). My reasoning for
making it a separate endpoint is that this is an activity I expect people will
want to do a lot, avoiding the query parameter makes for a slightly nicer API.
But it is repetition in the code.
(There are some other minor issues but I think I agree with the points made
there.)
My answers:
(1) slight preference for the `/catalog` prefix
(2) strong pref to deprecate old calls - they are redundant and multiple is
confusing
(3) strong pref to stay with `/v1` for now
(4) slight pref for explicit `[/catalog]/subtypes` endpoint
---
