<div dir="ltr">Thanks for the comments, Zane.<br><div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Nov 14, 2013 at 9:56 AM, Zane Bitter <span dir="ltr"><<a href="mailto:zbitter@redhat.com" target="_blank">zbitter@redhat.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">On 14/11/13 17:19, Christopher Armstrong wrote:<br>
</div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">
<a href="http://docs.heatautoscale.apiary.io/" target="_blank">http://docs.heatautoscale.<u></u>apiary.io/</a><br>
<br>
I've thrown together a rough sketch of the proposed API for autoscaling.<br>
It's written in API-Blueprint format (which is a simple subset of<br>
Markdown) and provides schemas for inputs and outputs using JSON-Schema.<br></div>
The source document is currently atÂ<div class="im"><br>
<a href="https://github.com/radix/heat/raw/as-api-spike/autoscaling.apibp" target="_blank">https://github.com/radix/heat/<u></u>raw/as-api-spike/autoscaling.<u></u>apibp</a><br>
<br>
<br>
Things we still need to figure out:<br>
<br>
- how to scope projects/domains. put them in the URL? get them from the<br>
token?<br>
- how webhooks are done (though this shouldn't affect the API too much;<br>
they're basically just opaque)<br>
</div></blockquote>
<br>
My 2c: the way I designed the Heat API was such that extant stacks can be addressed uniquely by name. Humans are pretty good with names, not so much with 128 bit numbers. The consequences of this for the design were:<br>

 - names must be unique per-tenant<br>
 - the tenant-id appears in the endpoint URL<br>
<br>
However, the rest of OpenStack seems to have gone in a direction where the "name" is really just a comment field, everything is addressed only by UUID. A consequence of this is that it renders the tenant-id in the URL pointless, so many projects are removing it.<br>

<br>
Unfortunately, one result is that if you create a resource and e.g. miss the Created response for any reason and thus do not have the UUID, there is now no safe, general automated way to delete it again. (There are obviously heuristics you could try.) To solve this problem, there is a proposal floating about for clients to provide another unique ID when making the request, which would render a retry of the request idempotent. That's insufficient, though, because if you decide to roll back instead of retry you still need a way to delete using only this ID.<br>

<br>
So basically, that design sucks for both humans (who have to remember UUIDs instead of names) and machines (Heat). However, it appears that I am in a minority of one on this point, so take it with a grain of salt.<div class="im">
<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Please read and comment :)<br>
</blockquote>
<br></div>
A few comments...<br>
<br>
#1 thing is that the launch configuration needs to be somehow represented. In general we want the launch configuration to be a provider template, but we'll want to create a shortcut for the obvious case of just scaling servers. Maybe we pass a provider template (or URL) as well as parameters, and the former is optional.<br>

<br></blockquote><div><br></div><div>I'm a little unclear as to what point you're making here. Right now, the "launch configuration" is specified in the scaling group by the "resources" property of the request json body. It's not a full template, but just a "snippet" of a set of resources you want scaled.</div>
<div><br></div><div>As an aside, maybe we should replace this with a singlular "resource" and allow people to use a Stack resource if they want to represent multiple resources.</div><div><br></div><div>I guess we can have a simpler API for using an old-style, server-specific "launch configuration", but I am skeptical of the benefit, since specifying a single Instance resource is pretty simple.</div>
<div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Successful creates should return 201 Created, not 200 OK.<br></blockquote><div><br></div><div>Okay, I'll update that. I think I also forgot to specify some success responses for things that need them.</div><div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Responses from creates should include the UUID as well as the URI. (Getting into minor details here.)<br></blockquote><div><br></div><div>Okay.</div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

<br>
Policies are scoped within groups, so do they need a unique id or would a name do?<br></blockquote><div><br></div><div>I guess we could get rid of the ID and only have a name, what do other people think?</div><div> </div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
I'm not sure I understand the webhooks part... webhook-exec is the thing that e.g. Ceilometer will use to signal an alarm, right? Why is it not called something like /groups/{group_id}/policies/{<u></u>policy_id}/alarm ? (Maybe because it requires different auth middleware? Or does it?)<br>
</blockquote><div><br></div><div>Mostly because it's unnecessary. The idea was to generate a secret, opaque, revokable ID that maps to the specific policy.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

<br>
And the other ones are setting up the notification actions? Can we call them notifications instead of webhooks? (After all, in the future we will probably want to add Marconi support, and maybe even Mistral support.) And why are these attached to the policy? Isn't the notification connected to changes in the group, rather than anything specific to the policy? Am I misunderstanding how this works? What is the difference between 'uri' and 'capability_uri'?<br>
</blockquote><div><br></div><div><br></div><div>Policies represent ways to change a group ("add +5% to this group"). Webhooks execute policies.<br></div><div><br></div><div>A "capability URI" is a URI which represents a capability to do something all by itself. capability_uri would be the webhook-exec thing. The regular URI would be the thing under /groups/{group_id}/policies/{policy_id}/webhooks. That URI needs to exist so you can perform the DELETE operation on it. (but you can't DELETE the capability_uri, only POST to it to execute the policy).</div>
<div> </div><div><br></div><div>I'll think more about webhooks vs notifications.</div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
You need to define PUT/PATCH methods for most of these also, obviously (I assume you just want to get this part nailed down first).<br></blockquote><div><br></div><div>Yeah, I do. Thanks for reminding me :)</div><div> </div>
</div><div><br></div>-- <br><div dir="ltr"><div>IRC: radix</div>Christopher Armstrong<div>Rackspace</div></div>
</div></div>