Open Stack

tl;dr POST /$tenant/stacks/$stack/resources/ ?


== background ==

While thinking about the Autoscaling API, Thomas Hervé and I had the
following consideration:

- autoscaling is implemented as a set of Heat Resources
- there are already general APIs for looking at resources generically:
  - resource-show (GET /$tenant/stacks/$stack/resources/$id)
  - resource-metadata (GET /$tenantt/stacks/$stack/resources/$id/metadata)
  - resource-list (GET /$tenant/stacks/$stack/resources/)
- we want to be able to create and configure autoscaling resources
through the API
- maybe we should implement POST for resources?

This is basically the gist of the question. I believe the answer
should be the same as the answer about any other type of resource we
might want to manipulate through the API -- it seems best that either
all resource types are manipulated through a generic resource
manipulation API, or they should all have their own specific ReST
collection.

Actually, I could also imagine a situation where only generic
operations on common resource metadata are allowed via
/$tenant/stacks/$stack/resources/, and resource-specific manipulation
is done via resource-specific collections -- I don't know how ReSTy
that is, though.

I'll get to specifics. There are two ways I can imagine the autoscale
API looking. I'll avoid the word "resource" when referring to ReST
resources and just talk about "collections" and "paths", since
"resource" in this context also means Heat resources.

== resource-specific paths ==

One is basically just like Otter's: http://docs.autoscale.apiary.io/

This provides paths like /$tenant/groups/$id (for an autoscaling
group), /$tenant/groups/$id/policies (for a policy), etc. These
variously support GET for reading as well as POST and PUT for
manipulation.

We can use "/v1.0/{tenantId}/groups/{groupId}/policies" as an example
operation. We POST JSON describing a new scaling policy to create to a
new scaling policy.

== generic paths ==

The alternative is to say that autoscaling groups, policies, etc are
all Just Heat Resources, and Heat resources already have a ReST
collection at /$tenant/resources/.

In this option, the alternative to POSTing to
/$tenant/groups/$id/policies would be to post directly to
/$tenant/resources/, with a body exactly like in the previous example,
but with two more JSON attributes:

- the type of the resource, in this case something like
"AWS::AutoScaling::ScalingPolicy"
- the group ID that the new policy should be associated with, since
it's not specified in the URL.

One concern I have is about how well we can specify a strict schema of
inputs and outputs to the resources/ collection -- I'm particular
interested in JSON hyperschema. I'm not sure how it handles
heterogeneous collections like this.

--
IRC: radix
Christopher Armstrong
Rackspace