Heat/Blueprints/V2API

Area to start documenting changes required for a Heat v2 API:


 * 1) Remove tenant ID from the endpoint path
 * 2) Remove references to tenant in the request body (we can derive it from the context)
 * 3) Remove template_url from the request POST (always load the template in the client, like we do for provider templates?)
 * 4) Pass parameters as dict/json?
 * 5) Report resource/stack state in a more intelligent way (separate action/status for a start)
 * 6) Fix return status codes e.g for asynchronous operations return 202 instead of a mixture of 200/201/204
 * 7) Fix noecho booleans https://bugs.launchpad.net/heat/+bug/1364507
 * 8) Enforce symmetric request and response bodies, e.g. when create sends a {'stack': {}}, response should contain {'stack': {}}, this is for better alignment with OpenStack SDK, because oslo apiclient is deprecating [Qiming added]
 * 9) Add API version query/negotiation support, i.e. API version and engine version [Qiming added]
 * 10) Use form "sort=key:dir" for queries instead of "sort_keys=k1,k2 sort_dir=asc" [Qiming added]
 * 11) Add counting for the list response like {count:, other response},  which helps clients to do the pagination.  [kanagaraj-manickam added]
 * 12) Provide a RESTful interface to actions (i.e. actions are considered resources, they are recorded in db, can be listed, queried, etc.) [miguelgrinberg added]
 * 13) Add hypermedia to the Heat API, at least at a basic level for now [miguelgrinberg added]
 * 14) the signal api should have a structured definition of the details [Qiming added]

TODO(asalkeld):
 * 1) add actions (pause/resume/...)
 * 2) change abandon -> export (not destructive, as it's dangerous)
 * 3) add signal hooks (could arguebly be it's own little service)
 * 4) remove events (rely on notifications instead)
 * 5) move software config to it's own endpoint (not strictly a part of Heat)
 * 6) add support for using glance catalog by default?
 * 7) have a proper PATCH
 * 8) should we only have the environment (not have parameters and env)? Can be merged in the client.

Draft Spec [WORKINPROGRESS]
'''POST v2/stacks ''' Create a stack


 * stack_name: The name of the stack to create.


 * template: A JSON template to instantiate.


 * environment: A JSON envionment for the stack.


 * files: A map of file names (Provider resource templates, as referenced in the environment) to JSON template bodies.


 * parameters: A JSON map of parameter values


 * timeout_mins: The timeout for stack creation in minutes.


 * tags: Tags assigned to the stack. [by Qiming]


 * enable_rollback: Whether the stack can be rolled back. [by Qiming]

'''GET v2/stacks ''' Get a list of active stacks.


 * Allow getting a stack by name via filter parameters, e.g
 * GET v2/stacks?name=foo
 * ref https://review.openstack.org/#/c/57313/

'''GET v2/stacks/{stack_id} ''' Get data about a stack.

'''PUT v2/stacks/{stack_id} ''' Update a stack.

'''DELETE v2/stacks/{stack_id} ''' Delete a stack.

'''GET v2/stacks/{stack_id}/events ''' Get a list of events for a stack.

'''GET v2/stacks/{stack_id}/resources ''' Get a list of resources in a stack.

'''GET v2/stacks/{stack_id}/resources/{resource_name} ''' Get data about a resource. [Qiming: Use resource_id in URI to ease Unicode support?]

'''GET v2/stacks/{stack_id}/resources/{resource_name}/metadata ''' Get a resource's metadata. [Qiming: Use resource_id in URI to ease Unicode support?]

'''GET v2/events ''' Get a list of events for all resources. [Qiming: Make events a top level resources?]

'''GET v2/events?stack_name=foo&resource_name=bar ''' Get a list of events for specific stacks and/or resources. [Qiming: how about this?]

'''GET v2/stacks/{stack_id}/resources/events ''' Get a list of events for a stack resource. [miguelgrinberg: aren't this and the previous one the same? This one seems clearer IMHO]

'''GET v2/stacks/{stack_id}/resources/events/{event_id} ''' Get data about an event.

'''GET v2/stacks/{stack_id}/template ''' Retrieve a stack's template.

'''POST v2/validate_template ''' Validate a template.

'''GET v2/resource_types ''' Get a list of the template resource types that are supported. Response should include resource support status and resource version(s).