)]}'
{"guidelines/actions.rst":[{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"db8dba85aacecb40f91e0e8bb0ad52ce097af184","unresolved":false,"context_lines":[{"line_number":1,"context_line":".. _actions:"},{"line_number":2,"context_line":""},{"line_number":3,"context_line":"Actions"},{"line_number":4,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":5,"context_line":""},{"line_number":6,"context_line":"A common need of OpenStack APIs is to enable clients to trigger actions, with"}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_fdb38a08","line":3,"updated":"2016-01-18 15:04:47.000000000","message":"\"Commands\" might be clearer. Ironic right now has a spec under review that uses \"Transitions\". https://review.openstack.org/#/c/224022/, other API\u0027s use the term \"Tasks\"; If this an effort to get everyone to agree on the same word, we need to make sure the other projects are on board.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":8099,"name":"Graham Hayes","email":"gr@ham.ie","username":"graham"},"change_message_id":"9fc36891dd358955805f05a2353e8b15f1058ccb","unresolved":false,"context_lines":[{"line_number":17,"context_line":"*http://example.com/api/servers/123/reboot*. While this is a common technique,"},{"line_number":18,"context_line":"it conflicts with the REST principles in several ways:"},{"line_number":19,"context_line":""},{"line_number":20,"context_line":"    - REST requires that all URLs exposed by an API map to actual resources."},{"line_number":21,"context_line":"    - The abuse of actions in URLs converts the API into a procedural API, more"},{"line_number":22,"context_line":"      in line with RPC architectures such as SOAP."},{"line_number":23,"context_line":"    - Since the HTTP methods map directly to CRUD resource operations, there is"}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_9e42d266","line":20,"updated":"2016-01-15 19:12:21.000000000","message":"They are resources. You are creating an instance of a reboot on the parent resource.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":5441,"name":"Andrew Laski","email":"andrew@lascii.com","username":"alaski"},"change_message_id":"6178937835fdaccb50126f89373b358815de06a7","unresolved":false,"context_lines":[{"line_number":17,"context_line":"*http://example.com/api/servers/123/reboot*. While this is a common technique,"},{"line_number":18,"context_line":"it conflicts with the REST principles in several ways:"},{"line_number":19,"context_line":""},{"line_number":20,"context_line":"    - REST requires that all URLs exposed by an API map to actual resources."},{"line_number":21,"context_line":"    - The abuse of actions in URLs converts the API into a procedural API, more"},{"line_number":22,"context_line":"      in line with RPC architectures such as SOAP."},{"line_number":23,"context_line":"    - Since the HTTP methods map directly to CRUD resource operations, there is"}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_c25a5af2","line":20,"in_reply_to":"da6ed579_9e42d266","updated":"2016-01-18 16:30:37.000000000","message":"Creating a resource would be a valid approach to this, but in practice that\u0027s not often how it\u0027s done.  Using Nova as an example a POST that triggers an action does not create a new resource, it simply modifies the task_state of the instance resource.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":8099,"name":"Graham Hayes","email":"gr@ham.ie","username":"graham"},"change_message_id":"9fc36891dd358955805f05a2353e8b15f1058ccb","unresolved":false,"context_lines":[{"line_number":21,"context_line":"    - The abuse of actions in URLs converts the API into a procedural API, more"},{"line_number":22,"context_line":"      in line with RPC architectures such as SOAP."},{"line_number":23,"context_line":"    - Since the HTTP methods map directly to CRUD resource operations, there is"},{"line_number":24,"context_line":"      no clear choice of method to use to trigger an action."},{"line_number":25,"context_line":"    - An API with a large number of actions implemented with this technique"},{"line_number":26,"context_line":"      expose a complicated, polluted URL namespace that makes it very difficult"},{"line_number":27,"context_line":"      to implement hypermedia."}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_5e28da99","line":24,"updated":"2016-01-15 19:12:21.000000000","message":"POST - you are creating a resource.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":8099,"name":"Graham Hayes","email":"gr@ham.ie","username":"graham"},"change_message_id":"9fc36891dd358955805f05a2353e8b15f1058ccb","unresolved":false,"context_lines":[{"line_number":24,"context_line":"      no clear choice of method to use to trigger an action."},{"line_number":25,"context_line":"    - An API with a large number of actions implemented with this technique"},{"line_number":26,"context_line":"      expose a complicated, polluted URL namespace that makes it very difficult"},{"line_number":27,"context_line":"      to implement hypermedia."},{"line_number":28,"context_line":"    - Clients are forced to hardcode all these actions, increasing"},{"line_number":29,"context_line":"      client/server coupling."},{"line_number":30,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_be131664","line":27,"updated":"2016-01-15 19:12:21.000000000","message":"Not hugely. they also make it a lot clearer what is actually happening","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"db8dba85aacecb40f91e0e8bb0ad52ce097af184","unresolved":false,"context_lines":[{"line_number":24,"context_line":"      no clear choice of method to use to trigger an action."},{"line_number":25,"context_line":"    - An API with a large number of actions implemented with this technique"},{"line_number":26,"context_line":"      expose a complicated, polluted URL namespace that makes it very difficult"},{"line_number":27,"context_line":"      to implement hypermedia."},{"line_number":28,"context_line":"    - Clients are forced to hardcode all these actions, increasing"},{"line_number":29,"context_line":"      client/server coupling."},{"line_number":30,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_1d5d3e79","line":27,"in_reply_to":"da6ed579_be131664","updated":"2016-01-18 15:04:47.000000000","message":"I disagree. State machines can get complicated. Here\u0027s Ironic\u0027s example, which doesn\u0027t even include power and maintenance states. http://docs.openstack.org/developer/ironic/dev/states.html","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":8099,"name":"Graham Hayes","email":"gr@ham.ie","username":"graham"},"change_message_id":"9fc36891dd358955805f05a2353e8b15f1058ccb","unresolved":false,"context_lines":[{"line_number":26,"context_line":"      expose a complicated, polluted URL namespace that makes it very difficult"},{"line_number":27,"context_line":"      to implement hypermedia."},{"line_number":28,"context_line":"    - Clients are forced to hardcode all these actions, increasing"},{"line_number":29,"context_line":"      client/server coupling."},{"line_number":30,"context_line":""},{"line_number":31,"context_line":"For all the above reasons, the inclusion of actions in URLs is strongly"},{"line_number":32,"context_line":"discouraged."}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_5916b44c","line":29,"updated":"2016-01-15 19:12:21.000000000","message":"They are forced to hard code all actions?","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"db8dba85aacecb40f91e0e8bb0ad52ce097af184","unresolved":false,"context_lines":[{"line_number":26,"context_line":"      expose a complicated, polluted URL namespace that makes it very difficult"},{"line_number":27,"context_line":"      to implement hypermedia."},{"line_number":28,"context_line":"    - Clients are forced to hardcode all these actions, increasing"},{"line_number":29,"context_line":"      client/server coupling."},{"line_number":30,"context_line":""},{"line_number":31,"context_line":"For all the above reasons, the inclusion of actions in URLs is strongly"},{"line_number":32,"context_line":"discouraged."}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_7d931afb","line":29,"in_reply_to":"da6ed579_5916b44c","updated":"2016-01-18 15:04:47.000000000","message":"Perhaps replace the second clause with \", unless a resource that returns all valid actions is provided\".","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"db8dba85aacecb40f91e0e8bb0ad52ce097af184","unresolved":false,"context_lines":[{"line_number":57,"context_line":"The resource representation for an action resource has the following"},{"line_number":58,"context_line":"structure::"},{"line_number":59,"context_line":""},{"line_number":60,"context_line":"    {"},{"line_number":61,"context_line":"        \"name\": \"\u003caction_name\u003e\","},{"line_number":62,"context_line":"        \"args\": {"},{"line_number":63,"context_line":"            \"\u003carg1_name\u003e\": \"\"\u003carg1_value\u003e\"\","},{"line_number":64,"context_line":"            \"\u003carg2_name\u003e\": \"\"\u003carg2_value\u003e\"\","},{"line_number":65,"context_line":"            ..."},{"line_number":66,"context_line":"        }"},{"line_number":67,"context_line":"    }"},{"line_number":68,"context_line":""},{"line_number":69,"context_line":"When retrieving an action resource, the server can insert optional read-only"},{"line_number":70,"context_line":"attributes in the representation that provide status to the client::"}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_1da8deda","line":67,"range":{"start_line":60,"start_character":4,"end_line":67,"end_character":5},"updated":"2016-01-18 15:04:47.000000000","message":"You mention \"action_id\" later; add it here for clarity.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"db8dba85aacecb40f91e0e8bb0ad52ce097af184","unresolved":false,"context_lines":[{"line_number":78,"context_line":"        },"},{"line_number":79,"context_line":"        \"started_at\": \u003ctimestamp\u003e,"},{"line_number":80,"context_line":"        \"ended_at\": \u003ctimestamp_or_null\u003e,"},{"line_number":81,"context_line":"        \"status\": \"in_progress|completed|failed\""},{"line_number":82,"context_line":"    }"},{"line_number":83,"context_line":""},{"line_number":84,"context_line":"HTTP Methods"}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_9db4ce35","line":81,"range":{"start_line":81,"start_character":8,"end_line":81,"end_character":48},"updated":"2016-01-18 15:04:47.000000000","message":"Add pending, and/or indicate that the command status specifics are left to the implementor.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"db8dba85aacecb40f91e0e8bb0ad52ce097af184","unresolved":false,"context_lines":[{"line_number":81,"context_line":"        \"status\": \"in_progress|completed|failed\""},{"line_number":82,"context_line":"    }"},{"line_number":83,"context_line":""},{"line_number":84,"context_line":"HTTP Methods"},{"line_number":85,"context_line":"~~~~~~~~~~~~"},{"line_number":86,"context_line":""},{"line_number":87,"context_line":"To trigger an action, a corresponding action resource must be created. This is"}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_3082a953","line":84,"range":{"start_line":84,"start_character":0,"end_line":84,"end_character":12},"updated":"2016-01-18 15:04:47.000000000","message":"I\u0027d call out the expected behavior of the GET /actions endpoint here, i.e.. \"List all actions, pending, in_progress, or otherwise\" or something along those lines.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"21ba06543fbd0a45b0000ebf164e9e91b5564384","unresolved":false,"context_lines":[{"line_number":97,"context_line":"If the action is started successfully, the server must respond with a 201"},{"line_number":98,"context_line":"status code and include a ``Location`` header with the unique URL of the action"},{"line_number":99,"context_line":"resource that the client can query for status on the action. In the example"},{"line_number":100,"context_line":"above, this URL would have the form */servers/\u003cserver_id\u003e/actions/\u003caction_id\u003e*."},{"line_number":101,"context_line":""},{"line_number":102,"context_line":"For APIs that wish to use a simpler implementation that does not require the"},{"line_number":103,"context_line":"use of individual action resources, the response can be 200 or 202 for"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3a29b11f_4db83a2a","line":100,"updated":"2015-10-22 23:13:15.000000000","message":"This approach is similar to \"task\" APIs which have been proposed in several openstack projects.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":5441,"name":"Andrew Laski","email":"andrew@lascii.com","username":"alaski"},"change_message_id":"6178937835fdaccb50126f89373b358815de06a7","unresolved":false,"context_lines":[{"line_number":97,"context_line":"If the action is started successfully, the server must respond with a 201"},{"line_number":98,"context_line":"status code and include a ``Location`` header with the unique URL of the action"},{"line_number":99,"context_line":"resource that the client can query for status on the action. In the example"},{"line_number":100,"context_line":"above, this URL would have the form */servers/\u003cserver_id\u003e/actions/\u003caction_id\u003e*."},{"line_number":101,"context_line":""},{"line_number":102,"context_line":"For APIs that wish to use a simpler implementation that does not require the"},{"line_number":103,"context_line":"use of individual action resources, the response can be 200 or 202 for"}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_a5565004","line":100,"in_reply_to":"3a29b11f_4db83a2a","updated":"2016-01-18 16:30:37.000000000","message":"This is very much like the tasks API that has been discussed in Nova for a few cycles now.  There has been no disagreement that it would be a better API experience than what is offered now.  All that\u0027s left is to nitpick the details, like calling it a task rather than an action :)  \u0027actions\u0027 would be confusing in Nova because current actions fall under \u0027/servers/\u003cserver_id/action\u0027.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"21ba06543fbd0a45b0000ebf164e9e91b5564384","unresolved":false,"context_lines":[{"line_number":103,"context_line":"use of individual action resources, the response can be 200 or 202 for"},{"line_number":104,"context_line":"synchronous or asynchronous actions respectively. In the case of an"},{"line_number":105,"context_line":"asynchronous action, it is assumed that the client can obtain status by"},{"line_number":106,"context_line":"querying the parent resource."},{"line_number":107,"context_line":""},{"line_number":108,"context_line":"The remaining HTTP methods are considered optional, and only make sense when"},{"line_number":109,"context_line":"the API implements individual action resource URLs."}],"source_content_type":"text/x-rst","patch_set":2,"id":"3a29b11f_9a0f6636","line":106,"updated":"2015-10-22 23:13:15.000000000","message":"How correct is this assumption?\nI\u0027m probably thinking too much along the lines of the action/task analogy, but progress of the action should not necessarily reflect into a change in the status of the resource on which the action is executed - progress of the action is to be checked on the action itself.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"8a7f52ba5483a334680f6655ba711840f9bd8fd2","unresolved":false,"context_lines":[{"line_number":103,"context_line":"use of individual action resources, the response can be 200 or 202 for"},{"line_number":104,"context_line":"synchronous or asynchronous actions respectively. In the case of an"},{"line_number":105,"context_line":"asynchronous action, it is assumed that the client can obtain status by"},{"line_number":106,"context_line":"querying the parent resource."},{"line_number":107,"context_line":""},{"line_number":108,"context_line":"The remaining HTTP methods are considered optional, and only make sense when"},{"line_number":109,"context_line":"the API implements individual action resource URLs."}],"source_content_type":"text/x-rst","patch_set":2,"id":"da85f559_a5a45608","line":106,"in_reply_to":"3a29b11f_9a0f6636","updated":"2015-11-06 23:30:53.000000000","message":"Note the start of the paragraph: \"For APIs that wish to use a simpler implementation that does not require the use of individual action resources\". That is why in this scenario, status is assumed to be on the parent resource, as there is no action resource.\n\nThe ideal implementation would have an action resource created for every action, and the response to the POST request that creates the action returns 202 and contains a Location header with the resource that can be used to check status, which I agree, can be the action resource itself.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"21ba06543fbd0a45b0000ebf164e9e91b5564384","unresolved":false,"context_lines":[{"line_number":114,"context_line":"for that action."},{"line_number":115,"context_line":""},{"line_number":116,"context_line":"A ``DELETE`` request can be sent to an individual action URL to request the"},{"line_number":117,"context_line":"cancellation of an action currently in progress."},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"A ``PUT`` request can be sent to an individual action URL to update the"},{"line_number":120,"context_line":"arguments of the action."}],"source_content_type":"text/x-rst","patch_set":2,"id":"3a29b11f_ed6fc6c1","line":117,"updated":"2015-10-22 23:13:15.000000000","message":"Does a completed action auto-destroy itself?","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":12606,"name":"Miguel Grinberg","email":"miguel.grinberg@gmail.com","username":"miguelgrinberg"},"change_message_id":"8a7f52ba5483a334680f6655ba711840f9bd8fd2","unresolved":false,"context_lines":[{"line_number":114,"context_line":"for that action."},{"line_number":115,"context_line":""},{"line_number":116,"context_line":"A ``DELETE`` request can be sent to an individual action URL to request the"},{"line_number":117,"context_line":"cancellation of an action currently in progress."},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"A ``PUT`` request can be sent to an individual action URL to update the"},{"line_number":120,"context_line":"arguments of the action."}],"source_content_type":"text/x-rst","patch_set":2,"id":"da85f559_654bce2c","line":117,"in_reply_to":"3a29b11f_ed6fc6c1","updated":"2015-11-06 23:30:53.000000000","message":"My opinion is that completed actions should not auto-destroy. That way they can be queried after the task is done, or query the history of actions performed on a resource.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"db8dba85aacecb40f91e0e8bb0ad52ce097af184","unresolved":false,"context_lines":[{"line_number":114,"context_line":"for that action."},{"line_number":115,"context_line":""},{"line_number":116,"context_line":"A ``DELETE`` request can be sent to an individual action URL to request the"},{"line_number":117,"context_line":"cancellation of an action currently in progress."},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"A ``PUT`` request can be sent to an individual action URL to update the"},{"line_number":120,"context_line":"arguments of the action."}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_100c453a","line":117,"in_reply_to":"da85f559_654bce2c","updated":"2016-01-18 15:04:47.000000000","message":"+1 for not destroying.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"6c0340926c737e73fa10c54ad9f36ad83a7b7c7c","unresolved":false,"context_lines":[{"line_number":117,"context_line":"cancellation of an action currently in progress."},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"A ``PUT`` request can be sent to an individual action URL to update the"},{"line_number":120,"context_line":"arguments of the action."}],"source_content_type":"text/x-rst","patch_set":2,"id":"7a740942_6cd61ac7","line":120,"updated":"2015-12-04 14:56:05.000000000","message":"What does this actually mean? I\u0027ve already created the action, it might be pending or already done what does changing its arguments do to the action? Is this allowing for unwarranted complexity that we can avoid by disallowing it entirely or, if not, should we at least mention that this would 4xx when the action has already started and it is too late to change?","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":5441,"name":"Andrew Laski","email":"andrew@lascii.com","username":"alaski"},"change_message_id":"6178937835fdaccb50126f89373b358815de06a7","unresolved":false,"context_lines":[{"line_number":117,"context_line":"cancellation of an action currently in progress."},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"A ``PUT`` request can be sent to an individual action URL to update the"},{"line_number":120,"context_line":"arguments of the action."}],"source_content_type":"text/x-rst","patch_set":2,"id":"da6ed579_0215d299","line":120,"in_reply_to":"7a740942_3c327611","updated":"2016-01-18 16:30:37.000000000","message":"I can\u0027t think of an example where this would be feasible to allow in practice.  Perhaps including such an example would help justify this.  Instead I would think that it would be simpler to DELETE, which would hopefully trigger a rollback to before the action began, and then POST an updated version of the action.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"1548d5e97523d79e3e70f3acf0f6e4f1893a3f74","unresolved":false,"context_lines":[{"line_number":117,"context_line":"cancellation of an action currently in progress."},{"line_number":118,"context_line":""},{"line_number":119,"context_line":"A ``PUT`` request can be sent to an individual action URL to update the"},{"line_number":120,"context_line":"arguments of the action."}],"source_content_type":"text/x-rst","patch_set":2,"id":"7a740942_3c327611","line":120,"in_reply_to":"7a740942_6cd61ac7","updated":"2015-12-04 19:45:40.000000000","message":"good questions, i think it could be very difficult to update actions mid-processing. i agree with your assessment that we should avoid adding the inherent complexity of updating actions that have begun.\n\ni have a feeling this is added as an opening for services for which it makes sense to update the arguments.\n\n+1 to returning 4xx if an update is inappropriate.","commit_id":"339eec20cee62484ce6ad3be0e98ed59dca05d90"}]}