Difference between revisions of "Heat/Blueprints/V2API"
(16 intermediate revisions by 7 users not shown) | |||
Line 5: | Line 5: | ||
# Remove template_url from the request POST (always load the template in the client, like we do for provider templates?) | # 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? | # 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]=== | === Draft Spec [WORKINPROGRESS]=== | ||
Line 10: | Line 30: | ||
'''POST v2/stacks <br />''' | '''POST v2/stacks <br />''' | ||
Create a stack<br /> | Create a stack<br /> | ||
− | :stack_name | + | :stack_name: The name of the stack to create.<br /> |
− | :template | + | :template: A JSON template to instantiate.<br /> |
− | :environment | + | :environment: A JSON envionment for the stack.<br /> |
− | :files | + | :files: A map of file names (Provider resource templates, as referenced in the environment) to JSON template bodies.<br /> |
− | :parameters | + | :parameters: A JSON map of parameter values<br /> |
− | :timeout_mins | + | :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 /> | + | '''GET v2/stacks<br />''' |
Get a list of active stacks. | Get a list of active stacks. | ||
− | GET v2/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 | + | '''GET v2/stacks/{stack_id}<br />''' |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
Get data about a stack. | Get data about a stack. | ||
− | PUT v2/stacks | + | '''PUT v2/stacks/{stack_id}<br />''' |
Update a stack. | Update a stack. | ||
− | DELETE v2/stacks | + | '''DELETE v2/stacks/{stack_id}<br />''' |
Delete a stack. | Delete a stack. | ||
− | GET v2/stacks | + | '''GET v2/stacks/{stack_id}/events<br />''' |
Get a list of events for a stack. | Get a list of events for a stack. | ||
− | GET v2/stacks | + | '''GET v2/stacks/{stack_id}/resources<br />''' |
Get a list of resources in a stack. | Get a list of resources in a stack. | ||
− | GET v2/stacks/{ | + | '''GET v2/stacks/{stack_id}/resources/{resource_name}<br />''' |
− | Get | + | 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. [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/ | + | '''GET v2/events?stack_name=foo&resource_name=bar<br />''' |
− | Get a | + | Get a list of events for specific stacks and/or resources. [Qiming: how about this?] |
− | GET v2/stacks | + | '''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 | + | '''GET v2/stacks/{stack_id}/resources/events/{event_id}<br />''' |
Get data about an event. | Get data about an event. | ||
− | GET v2/stacks | + | '''GET v2/stacks/{stack_id}/template<br />''' |
Retrieve a stack's template. | Retrieve a stack's template. | ||
− | POST v2/validate_template<br /> | + | '''POST v2/validate_template<br />''' |
Validate a template. | Validate a template. | ||
− | GET v2/resource_types<br /> | + | '''GET v2/resource_types<br />''' |
Get a list of the template resource types that are supported. | Get a list of the template resource types that are supported. | ||
+ | Response should include resource support status and resource version(s). |
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).