Difference between revisions of "Heat/Blueprints/V2API"

Latest revision as of 18:14, 17 November 2015

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

Remove tenant ID from the endpoint path
Remove references to tenant in the request body (we can derive it from the context)
Remove template_url from the request POST (always load the template in the client, like we do for provider templates?)
Pass parameters as dict/json?
Report resource/stack state in a more intelligent way (separate action/status for a start)
Fix return status codes e.g for asynchronous operations return 202 instead of a mixture of 200/201/204
Fix noecho booleans https://bugs.launchpad.net/heat/+bug/1364507
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]
Add API version query/negotiation support, i.e. API version and engine version [Qiming added]
Use form "sort=key:dir" for queries instead of "sort_keys=k1,k2 sort_dir=asc" [Qiming added]
Add counting for the list response like {count: <number of records>, other response}, which helps clients to do the pagination. [kanagaraj-manickam added]
Provide a RESTful interface to actions (i.e. actions are considered resources, they are recorded in db, can be listed, queried, etc.) [miguelgrinberg added]
Add hypermedia to the Heat API, at least at a basic level for now [miguelgrinberg added]
the signal api should have a structured definition of the details [Qiming added]

TODO(asalkeld):

add actions (pause/resume/...)
change abandon -> export (not destructive, as it's dangerous)
add signal hooks (could arguebly be it's own little service)
remove events (rely on notifications instead)
move software config to it's own endpoint (not strictly a part of Heat)
add support for using glance catalog by default?
have a proper PATCH
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).

@@ Line 8: / Line 8: @@
 # Fix return status codes e.g for asynchronous operations return 202 instead of a mixture of 200/201/204
 # Fix noecho booleans https://bugs.launchpad.net/heat/+bug/1364507
+# 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]
+# Add API version query/negotiation support, i.e. API version and engine version [Qiming added]
+# Use form "sort=key:dir" for queries instead of "sort_keys=k1,k2 sort_dir=asc" [Qiming added]
+# Add counting for the list response like {count: <number of records>, other response},  which helps clients to do the pagination.  [kanagaraj-manickam added]
+# Provide a RESTful interface to actions (i.e. actions are considered resources, they are recorded in db, can be listed, queried, etc.) [miguelgrinberg added]
+# Add hypermedia to the Heat API, at least at a basic level for now [miguelgrinberg added]
+# the signal api should have a structured definition of the details [Qiming added]
 TODO(asalkeld):
@@ Line 30: / Line 36: @@
 :parameters: A JSON map of parameter values<br />
 :timeout_mins: The timeout for stack creation in minutes.<br />
+:tags: Tags assigned to the stack. [by Qiming]<br />
+:enable_rollback: Whether the stack can be rolled back. [by Qiming] <br />
 '''GET v2/stacks<br />'''
@@ Line 54: / Line 62: @@
 '''GET v2/stacks/{stack_id}/resources/{resource_name}<br />'''
-Get data about a resource.
+Get data about a resource. [Qiming: Use resource_id in URI to ease Unicode support?]
 '''GET v2/stacks/{stack_id}/resources/{resource_name}/metadata<br />'''
-Get a resource's metadata.
+Get a resource's metadata. [Qiming: Use resource_id in URI to ease Unicode support?]
+'''GET v2/events<br />'''
+Get a list of events for all resources. [Qiming: Make events a top level resources?]
+'''GET v2/events?stack_name=foo&resource_name=bar<br />'''
+Get a list of events for specific stacks and/or resources. [Qiming: how about this?]
 '''GET v2/stacks/{stack_id}/resources/events<br />'''
-Get a list of events for a stack resource.
+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}<br />'''