)]}'
{"guidelines/pagination_filter_sort.rst":[{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"fe9db2329a38744013d1a9331b7eb2313614b4cb","unresolved":false,"context_lines":[{"line_number":6,"context_line":"and sorting capabilities in a project\u0027s public REST API."},{"line_number":7,"context_line":""},{"line_number":8,"context_line":"Pagination"},{"line_number":9,"context_line":"----------"},{"line_number":10,"context_line":""},{"line_number":11,"context_line":"To reduce load on the service, many projects have implemented pagination for"},{"line_number":12,"context_line":"list operations, see [2]. Pagination supports to return a maximum number of"}],"source_content_type":"text/x-rst","patch_set":1,"id":"ba3cc151_24f8217c","line":9,"updated":"2015-07-06 19:40:20.000000000","message":"+1","commit_id":"968413db438e10b505c88f9c4fb981563341284c"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"38b4518404e67b20e706769701130bb78780cf18","unresolved":false,"context_lines":[{"line_number":6,"context_line":"and sorting capabilities in a project\u0027s public REST API."},{"line_number":7,"context_line":""},{"line_number":8,"context_line":"Pagination"},{"line_number":9,"context_line":"----------"},{"line_number":10,"context_line":""},{"line_number":11,"context_line":"To reduce load on the service, many projects have implemented pagination for"},{"line_number":12,"context_line":"list operations, see [2]. Pagination supports to return a maximum number of"}],"source_content_type":"text/x-rst","patch_set":1,"id":"fa32b979_7bdb984f","line":9,"updated":"2015-06-24 20:10:08.000000000","message":"this section might also contain a guideline for building responses with links to previous and next pages of data.","commit_id":"968413db438e10b505c88f9c4fb981563341284c"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"fe9db2329a38744013d1a9331b7eb2313614b4cb","unresolved":false,"context_lines":[{"line_number":9,"context_line":"----------"},{"line_number":10,"context_line":""},{"line_number":11,"context_line":"To reduce load on the service, many projects have implemented pagination for"},{"line_number":12,"context_line":"list operations, see [2]. Pagination supports to return a maximum number of"},{"line_number":13,"context_line":"items at a time. To navigate the collection, the parameters \u0027limit\u0027, \u0027marker\u0027"},{"line_number":14,"context_line":"and \u0027page_reverse\u0027 can be set in the URI."},{"line_number":15,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"ba3cc151_44f52581","line":12,"updated":"2015-07-06 19:40:20.000000000","message":"Can you use the actual RST footnote syntax instead?","commit_id":"968413db438e10b505c88f9c4fb981563341284c"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"38b4518404e67b20e706769701130bb78780cf18","unresolved":false,"context_lines":[{"line_number":13,"context_line":"items at a time. To navigate the collection, the parameters \u0027limit\u0027, \u0027marker\u0027"},{"line_number":14,"context_line":"and \u0027page_reverse\u0027 can be set in the URI."},{"line_number":15,"context_line":""},{"line_number":16,"context_line":"The \u0027limit\u0027 parameter sets the page size. The \u0027marker\u0027 parameter is the ID of"},{"line_number":17,"context_line":"an item. \u0027page_reverse\u0027 parameter sets the page direction. All these parameters"},{"line_number":18,"context_line":"are optional. By default, \u0027page_reverse\u0027 is set to \u0027False\u0027, which means to"},{"line_number":19,"context_line":"retrieve the next page."}],"source_content_type":"text/x-rst","patch_set":1,"id":"fa32b979_1b4fec34","line":16,"updated":"2015-06-24 20:10:08.000000000","message":"it might be better to introduce marker at the end.\nMarker is a reference item identifier; the response will return items starting from the marker if \u0027page_reverse\u0027 is False, otherwise it will return \"limit\" items up to the marker item.","commit_id":"968413db438e10b505c88f9c4fb981563341284c"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"fe9db2329a38744013d1a9331b7eb2313614b4cb","unresolved":false,"context_lines":[{"line_number":14,"context_line":"and \u0027page_reverse\u0027 can be set in the URI."},{"line_number":15,"context_line":""},{"line_number":16,"context_line":"The \u0027limit\u0027 parameter sets the page size. The \u0027marker\u0027 parameter is the ID of"},{"line_number":17,"context_line":"an item. \u0027page_reverse\u0027 parameter sets the page direction. All these parameters"},{"line_number":18,"context_line":"are optional. By default, \u0027page_reverse\u0027 is set to \u0027False\u0027, which means to"},{"line_number":19,"context_line":"retrieve the next page."},{"line_number":20,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"ba3cc151_e4f1d996","line":17,"updated":"2015-07-06 19:40:20.000000000","message":"If a marker item disappears (is deleted) what is the API behavior? To start from the beginning?","commit_id":"968413db438e10b505c88f9c4fb981563341284c"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"38b4518404e67b20e706769701130bb78780cf18","unresolved":false,"context_lines":[{"line_number":23,"context_line":"- Only limit specified:"},{"line_number":24,"context_line":""},{"line_number":25,"context_line":"  + \u0027\u0027limit\u003d10\u0027\u0027"},{"line_number":26,"context_line":"  + Return the first page of data"},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"- \u0027marker\u0027 is specified:"},{"line_number":29,"context_line":""}],"source_content_type":"text/x-rst","patch_set":1,"id":"fa32b979_bb3920a6","line":26,"updated":"2015-06-24 20:10:08.000000000","message":"\"The first 10 items starting from the beginning\" would be more accurate","commit_id":"968413db438e10b505c88f9c4fb981563341284c"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"c2a5d29f47a46a718b10235361bc963feb4a3c1b","unresolved":false,"context_lines":[{"line_number":32,"context_line":""},{"line_number":33,"context_line":"- All the three parameters are specified:"},{"line_number":34,"context_line":""},{"line_number":35,"context_line":"  + \u0027\u0027limit\u003d10\u0026marker\u003d\u003cuuid\u003e\u0026page_reverse\u003dFalse\u0027\u0027"},{"line_number":36,"context_line":"  + Return the previous page of data before the item with \u003cuuid\u003e"},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"If the client requests a limit beyond the maximum limit configured by the"}],"source_content_type":"text/x-rst","patch_set":1,"id":"fa32b979_dd83e301","line":35,"updated":"2015-06-24 05:10:43.000000000","message":"we should describe valid value for limit, like \u0027-1\u0027 doesn\u0027t supported, right?","commit_id":"968413db438e10b505c88f9c4fb981563341284c"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"38b4518404e67b20e706769701130bb78780cf18","unresolved":false,"context_lines":[{"line_number":32,"context_line":""},{"line_number":33,"context_line":"- All the three parameters are specified:"},{"line_number":34,"context_line":""},{"line_number":35,"context_line":"  + \u0027\u0027limit\u003d10\u0026marker\u003d\u003cuuid\u003e\u0026page_reverse\u003dFalse\u0027\u0027"},{"line_number":36,"context_line":"  + Return the previous page of data before the item with \u003cuuid\u003e"},{"line_number":37,"context_line":""},{"line_number":38,"context_line":"If the client requests a limit beyond the maximum limit configured by the"}],"source_content_type":"text/x-rst","patch_set":1,"id":"fa32b979_1b660cbb","line":35,"in_reply_to":"fa32b979_dd83e301","updated":"2015-06-24 20:10:08.000000000","message":"make sense","commit_id":"968413db438e10b505c88f9c4fb981563341284c"},{"author":{"_account_id":5754,"name":"Alex Xu","email":"hejie.xu@intel.com","username":"xuhj"},"change_message_id":"c2a5d29f47a46a718b10235361bc963feb4a3c1b","unresolved":false,"context_lines":[{"line_number":38,"context_line":"If the client requests a limit beyond the maximum limit configured by the"},{"line_number":39,"context_line":"deployment, the server returns the maximum limit number of items. If \u0027marker\u0027"},{"line_number":40,"context_line":"is not specified and \u0027page_reverse\u0027 is set to \u0027True\u0027, then no items need to be"},{"line_number":41,"context_line":"returned."},{"line_number":42,"context_line":""},{"line_number":43,"context_line":"Filtering"},{"line_number":44,"context_line":"---------"}],"source_content_type":"text/x-rst","patch_set":1,"id":"fa32b979_5d991378","line":41,"updated":"2015-06-24 05:10:43.000000000","message":"I think we should describe the previous\u0026next page link in the response also.","commit_id":"968413db438e10b505c88f9c4fb981563341284c"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"770131773a831532bdaa2c02a90a66731045a629","unresolved":false,"context_lines":[{"line_number":8,"context_line":"Pagination"},{"line_number":9,"context_line":"----------"},{"line_number":10,"context_line":""},{"line_number":11,"context_line":"To reduce load on the service, many projects have implemented pagination for"},{"line_number":12,"context_line":"list operations, see [2]_. Pagination supports to return a maximum number of"},{"line_number":13,"context_line":"items at a time. To navigate the collection, the parameters \u0027limit\u0027, \u0027marker\u0027"},{"line_number":14,"context_line":"and \u0027page_reverse\u0027 can be set in the URI."}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba3cc151_07043f15","line":11,"updated":"2015-07-09 22:44:18.000000000","message":"I think \"to reduce load on the service\" is probably not entirely accurate, or at least not the only reason for doing paging.\n\nThis is probably a great point to start a bike-shedding-cum-yak-shaving session! But since it\u0027s totally unrelated to the topic of this patch, I will refrain from doing so ; )","commit_id":"889f9917d7302b46bbea8759d18f3751c13d93e4"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"80a6868f82bbfcd02f99e689cce3044cdaef25e4","unresolved":false,"context_lines":[{"line_number":8,"context_line":"Pagination"},{"line_number":9,"context_line":"----------"},{"line_number":10,"context_line":""},{"line_number":11,"context_line":"To reduce load on the service, many projects have implemented pagination for"},{"line_number":12,"context_line":"list operations, see [2]_. Pagination supports to return a maximum number of"},{"line_number":13,"context_line":"items at a time. To navigate the collection, the parameters \u0027limit\u0027, \u0027marker\u0027"},{"line_number":14,"context_line":"and \u0027page_reverse\u0027 can be set in the URI."}],"source_content_type":"text/x-rst","patch_set":3,"id":"9a41bdd9_787be0f5","line":11,"in_reply_to":"ba3cc151_07043f15","updated":"2015-07-14 16:02:05.000000000","message":"i agree with the reasoning here, i think it might be worthwhile to just drop the \"To reduce load on the service,\" and let the sentence start with \"Many projects have implemented...\"","commit_id":"889f9917d7302b46bbea8759d18f3751c13d93e4"},{"author":{"_account_id":6949,"name":"Bryan Davidson","email":"bryan.davidson@rackspace.com","username":"bryan-davidson"},"change_message_id":"6b56388850ad99e0bbae2d60eb35178cfe031b28","unresolved":false,"context_lines":[{"line_number":15,"context_line":""},{"line_number":16,"context_line":"- limit: determine the num of items on the response, which should be a"},{"line_number":17,"context_line":"         positive integer."},{"line_number":18,"context_line":"- page_reverse: set the page direction, which can only be \u0027True\u0027 or \u0027False\u0027."},{"line_number":19,"context_line":"- marker: the ID of a reference item."},{"line_number":20,"context_line":""},{"line_number":21,"context_line":"And the next previous page link and the next page link should be added to the"}],"source_content_type":"text/x-rst","patch_set":3,"id":"9a41bdd9_baadc185","line":18,"updated":"2015-07-15 03:34:36.000000000","message":"Do we really need a page_reverse option? It seems to only duplicate the sorting functionality mentioned later in the specification.","commit_id":"889f9917d7302b46bbea8759d18f3751c13d93e4"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"33fafa9a52217abd00eee38f0d65c79b88c7e0ca","unresolved":false,"context_lines":[{"line_number":16,"context_line":"- limit: determine the num of items on the response, which should be a"},{"line_number":17,"context_line":"         positive integer."},{"line_number":18,"context_line":"- page_reverse: set the page direction, which can only be \u0027True\u0027 or \u0027False\u0027."},{"line_number":19,"context_line":"- marker: the ID of a reference item."},{"line_number":20,"context_line":""},{"line_number":21,"context_line":"And the next previous page link and the next page link should be added to the"},{"line_number":22,"context_line":"\u0027XXX_links\u0027 dict on the response for list operations."}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba3cc151_9b728ae2","line":19,"updated":"2015-07-07 12:15:56.000000000","message":"What happens if a marker is specified that no longer exists? Is that a 404?","commit_id":"889f9917d7302b46bbea8759d18f3751c13d93e4"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"aa6cb31372f4d62a742634bc69a1d26621b39394","unresolved":false,"context_lines":[{"line_number":16,"context_line":"- limit: determine the num of items on the response, which should be a"},{"line_number":17,"context_line":"         positive integer."},{"line_number":18,"context_line":"- page_reverse: set the page direction, which can only be \u0027True\u0027 or \u0027False\u0027."},{"line_number":19,"context_line":"- marker: the ID of a reference item."},{"line_number":20,"context_line":""},{"line_number":21,"context_line":"And the next previous page link and the next page link should be added to the"},{"line_number":22,"context_line":"\u0027XXX_links\u0027 dict on the response for list operations."}],"source_content_type":"text/x-rst","patch_set":3,"id":"9a41bdd9_ff381ba2","line":19,"in_reply_to":"ba3cc151_623739e3","updated":"2015-07-15 02:46:17.000000000","message":"I think it\u0027s better to return a 400. it\u0027s a bad input, not a invalid uri.","commit_id":"889f9917d7302b46bbea8759d18f3751c13d93e4"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"770131773a831532bdaa2c02a90a66731045a629","unresolved":false,"context_lines":[{"line_number":16,"context_line":"- limit: determine the num of items on the response, which should be a"},{"line_number":17,"context_line":"         positive integer."},{"line_number":18,"context_line":"- page_reverse: set the page direction, which can only be \u0027True\u0027 or \u0027False\u0027."},{"line_number":19,"context_line":"- marker: the ID of a reference item."},{"line_number":20,"context_line":""},{"line_number":21,"context_line":"And the next previous page link and the next page link should be added to the"},{"line_number":22,"context_line":"\u0027XXX_links\u0027 dict on the response for list operations."}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba3cc151_623739e3","line":19,"in_reply_to":"ba3cc151_9b728ae2","updated":"2015-07-09 22:44:18.000000000","message":"From what I gather the current behaviour upon missing markers in several projects is to start from the beginning of the collection (ie: ignore the missing marker).\n\nThis is not ideal, but I can\u0027t see a better solution at the moment while relying on the marker + limit approach.","commit_id":"889f9917d7302b46bbea8759d18f3751c13d93e4"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"aa6cb31372f4d62a742634bc69a1d26621b39394","unresolved":false,"context_lines":[{"line_number":16,"context_line":"- limit: determine the num of items on the response, which should be a"},{"line_number":17,"context_line":"         positive integer."},{"line_number":18,"context_line":"- page_reverse: set the page direction, which can only be \u0027True\u0027 or \u0027False\u0027."},{"line_number":19,"context_line":"- marker: the ID of a reference item."},{"line_number":20,"context_line":""},{"line_number":21,"context_line":"And the next previous page link and the next page link should be added to the"},{"line_number":22,"context_line":"\u0027XXX_links\u0027 dict on the response for list operations."}],"source_content_type":"text/x-rst","patch_set":3,"id":"9a41bdd9_5f5027d4","line":19,"in_reply_to":"ba3cc151_9b728ae2","updated":"2015-07-15 02:46:17.000000000","message":"That\u0027s worth discussing.","commit_id":"889f9917d7302b46bbea8759d18f3751c13d93e4"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"770131773a831532bdaa2c02a90a66731045a629","unresolved":false,"context_lines":[{"line_number":50,"context_line":"Note that, all these parameters are optional. By default, \u0027page_reverse\u0027 is"},{"line_number":51,"context_line":"set to \u0027False\u0027, which means to retrieve the next page. If \u0027marker\u0027 is not set"},{"line_number":52,"context_line":"and \u0027page_reverse\u0027 is set to \u0027False\u0027, the response will be the first page. And"},{"line_number":53,"context_line":"if \u0027page_reverse\u0027 is set to \u0027True\u0027 and \u0027marker\u0027 is not set, the repsonse will"},{"line_number":54,"context_line":"be the last page."},{"line_number":55,"context_line":""},{"line_number":56,"context_line":"The response of the first page:"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba3cc151_6293b9a3","line":53,"updated":"2015-07-09 22:44:18.000000000","message":"typo: repsonse","commit_id":"889f9917d7302b46bbea8759d18f3751c13d93e4"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"770131773a831532bdaa2c02a90a66731045a629","unresolved":false,"context_lines":[{"line_number":85,"context_line":"If the client requests a limit beyond the maximum limit configured by the"},{"line_number":86,"context_line":"deployment, the results will be the maximum limit number of items. If \u0027marker\u0027"},{"line_number":87,"context_line":"is not specified and \u0027page_reverse\u0027 is set to \u0027True\u0027, then no items need to be"},{"line_number":88,"context_line":"returned."},{"line_number":89,"context_line":""},{"line_number":90,"context_line":"Filtering"},{"line_number":91,"context_line":"---------"}],"source_content_type":"text/x-rst","patch_set":3,"id":"ba3cc151_42c6b59a","line":88,"updated":"2015-07-09 22:44:18.000000000","message":"I don\u0027t want to be too pedant, but you can remind that negative limits are invalid, and using a negative limit is not recommended as an alternative way for doing what\u0027s achieved with page_revers","commit_id":"889f9917d7302b46bbea8759d18f3751c13d93e4"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"80a6868f82bbfcd02f99e689cce3044cdaef25e4","unresolved":false,"context_lines":[{"line_number":85,"context_line":"If the client requests a limit beyond the maximum limit configured by the"},{"line_number":86,"context_line":"deployment, the results will be the maximum limit number of items. If \u0027marker\u0027"},{"line_number":87,"context_line":"is not specified and \u0027page_reverse\u0027 is set to \u0027True\u0027, then no items need to be"},{"line_number":88,"context_line":"returned."},{"line_number":89,"context_line":""},{"line_number":90,"context_line":"Filtering"},{"line_number":91,"context_line":"---------"}],"source_content_type":"text/x-rst","patch_set":3,"id":"9a41bdd9_f8ddb0e0","line":88,"in_reply_to":"ba3cc151_42c6b59a","updated":"2015-07-14 16:02:05.000000000","message":"+1","commit_id":"889f9917d7302b46bbea8759d18f3751c13d93e4"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"aa6cb31372f4d62a742634bc69a1d26621b39394","unresolved":false,"context_lines":[{"line_number":85,"context_line":"If the client requests a limit beyond the maximum limit configured by the"},{"line_number":86,"context_line":"deployment, the results will be the maximum limit number of items. If \u0027marker\u0027"},{"line_number":87,"context_line":"is not specified and \u0027page_reverse\u0027 is set to \u0027True\u0027, then no items need to be"},{"line_number":88,"context_line":"returned."},{"line_number":89,"context_line":""},{"line_number":90,"context_line":"Filtering"},{"line_number":91,"context_line":"---------"}],"source_content_type":"text/x-rst","patch_set":3,"id":"9a41bdd9_3fb7633b","line":88,"in_reply_to":"ba3cc151_42c6b59a","updated":"2015-07-15 02:46:17.000000000","message":"Yeah, that\u0027s a good point to specify.","commit_id":"889f9917d7302b46bbea8759d18f3751c13d93e4"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"721d4e7170144dcf44c22b2455f20dfbb178fe48","unresolved":false,"context_lines":[{"line_number":9,"context_line":"----------"},{"line_number":10,"context_line":""},{"line_number":11,"context_line":"Many projects have implemented pagination for list operations, see [2]_."},{"line_number":12,"context_line":"Pagination supports to return a maximum number of items at a time. To navigate"},{"line_number":13,"context_line":"the collection, the parameters \u0027limit\u0027, \u0027marker\u0027 and \u0027page_reverse\u0027 can be set"},{"line_number":14,"context_line":"in the URI."},{"line_number":15,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"3a50d1a3_09a51c03","line":12,"updated":"2015-07-20 10:33:25.000000000","message":"s/supports to return/supports returning/\n\ns/at a time/in a single HTTP request/","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"721d4e7170144dcf44c22b2455f20dfbb178fe48","unresolved":false,"context_lines":[{"line_number":10,"context_line":""},{"line_number":11,"context_line":"Many projects have implemented pagination for list operations, see [2]_."},{"line_number":12,"context_line":"Pagination supports to return a maximum number of items at a time. To navigate"},{"line_number":13,"context_line":"the collection, the parameters \u0027limit\u0027, \u0027marker\u0027 and \u0027page_reverse\u0027 can be set"},{"line_number":14,"context_line":"in the URI."},{"line_number":15,"context_line":""},{"line_number":16,"context_line":"- limit: determine the num of items on the response, which should be a"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3a50d1a3_29cfb8b1","line":13,"updated":"2015-07-20 10:33:25.000000000","message":"-1 to a page_reverse parameter. We already have sorting parameters that are used for this purpose.","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"fbe224ecaefd19db0486ec0f952968ca22b4ed32","unresolved":false,"context_lines":[{"line_number":10,"context_line":""},{"line_number":11,"context_line":"Many projects have implemented pagination for list operations, see [2]_."},{"line_number":12,"context_line":"Pagination supports to return a maximum number of items at a time. To navigate"},{"line_number":13,"context_line":"the collection, the parameters \u0027limit\u0027, \u0027marker\u0027 and \u0027page_reverse\u0027 can be set"},{"line_number":14,"context_line":"in the URI."},{"line_number":15,"context_line":""},{"line_number":16,"context_line":"- limit: determine the num of items on the response, which should be a"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3a50d1a3_7fbece00","line":13,"in_reply_to":"3a50d1a3_29cfb8b1","updated":"2015-07-20 11:07:34.000000000","message":"I wonder if I correctly get your point. My concern is that what\u0027s the proper method to get the previous page. We have two alternative solutions.\nIf we don\u0027t add another \u0027page_reverse\u0027 param, we could provide the previous page link with reverse sort direction. However, the result will be in an opposite order.\nAlso we could use the first item of the previous page, but that\u0027s a little complex. To generate the url of the previous page, you need to find the previous item of the previous page to get the marker. If the previous page don\u0027t have enough items, the final result of previous page will include some items of current page.","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"721d4e7170144dcf44c22b2455f20dfbb178fe48","unresolved":false,"context_lines":[{"line_number":19,"context_line":"- marker: the ID of a reference item."},{"line_number":20,"context_line":""},{"line_number":21,"context_line":"And the next previous page link and the next page link should be added to the"},{"line_number":22,"context_line":"\u0027XXX_links\u0027 dict on the response for list operations."},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"A example of requests:"},{"line_number":25,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"3a50d1a3_09b43cf0","line":22,"updated":"2015-07-20 10:33:25.000000000","message":"Should just be _links, not XXX_links. _links is the JSON-HAL convention:\n\nhttp://blog.stateless.co/post/13296666138/json-linking-with-hal","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"ed5edce4a28a1dbb29d86d76e35245183e6e75c1","unresolved":false,"context_lines":[{"line_number":25,"context_line":""},{"line_number":26,"context_line":".. code::"},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"    XXX?limit\u003d2\u0026marker\u003d\u003cuuid\u003e\u0026page_reverse\u003dTrue"},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"The result will include 2 items after the reference item. And the next link"},{"line_number":31,"context_line":"and the previous link will be added in the reply:"}],"source_content_type":"text/x-rst","patch_set":5,"id":"9a41bdd9_9ab694f7","line":28,"updated":"2015-07-15 17:30:20.000000000","message":"I do agree that the page_reverse parameter is a duplicate of the sorting guidelines. Can you remove it?","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"92448e2da639378aa4ab43f3f27264a9f855edea","unresolved":false,"context_lines":[{"line_number":25,"context_line":""},{"line_number":26,"context_line":".. code::"},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"    XXX?limit\u003d2\u0026marker\u003d\u003cuuid\u003e\u0026page_reverse\u003dTrue"},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"The result will include 2 items after the reference item. And the next link"},{"line_number":31,"context_line":"and the previous link will be added in the reply:"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3a50d1a3_7c57a002","line":28,"updated":"2015-07-20 19:03:15.000000000","message":"I don\u0027t think I see how it\u0027s useful to providing previous page uri. If you use standard sort parameters, then reverse listings would have the same next/prev URIs with the addition of the sorting parameter.","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"62859ddb85bf525e882bef5a2a7f182dd8fda374","unresolved":false,"context_lines":[{"line_number":25,"context_line":""},{"line_number":26,"context_line":".. code::"},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"    XXX?limit\u003d2\u0026marker\u003d\u003cuuid\u003e\u0026page_reverse\u003dTrue"},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"The result will include 2 items after the reference item. And the next link"},{"line_number":31,"context_line":"and the previous link will be added in the reply:"}],"source_content_type":"text/x-rst","patch_set":5,"id":"9a41bdd9_ece6fbae","line":28,"in_reply_to":"9a41bdd9_9ab694f7","updated":"2015-07-16 03:47:55.000000000","message":"I know page_reverse is relevant to sorting. But I think it\u0027s useful and essential to provide the previous page uri with page_reverse. The sorting guideline doesn\u0027t have any talk about that. So what do you think if we put the Pagination guideline after Sorting guideline.","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"721d4e7170144dcf44c22b2455f20dfbb178fe48","unresolved":false,"context_lines":[{"line_number":35,"context_line":"    {"},{"line_number":36,"context_line":"        \"XXX_links\": ["},{"line_number":37,"context_line":"            {"},{"line_number":38,"context_line":"                \"href\": \"XXX?limit\u003d2\u0026marker\u003d\u003clast_item_uuid\u003e\","},{"line_number":39,"context_line":"                \"rel\": \"next\""},{"line_number":40,"context_line":"            },"},{"line_number":41,"context_line":"            {"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3a50d1a3_09fe7c6b","line":38,"updated":"2015-07-20 10:33:25.000000000","message":"It might be worth noting that any sorting and filtering parameters will also be included in this link. Therefore, I\u0027d recommend moving the Pagination section to the *bottom* of this guideline page, after the discussion of sorting and filtering parameters.","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"fbe224ecaefd19db0486ec0f952968ca22b4ed32","unresolved":false,"context_lines":[{"line_number":35,"context_line":"    {"},{"line_number":36,"context_line":"        \"XXX_links\": ["},{"line_number":37,"context_line":"            {"},{"line_number":38,"context_line":"                \"href\": \"XXX?limit\u003d2\u0026marker\u003d\u003clast_item_uuid\u003e\","},{"line_number":39,"context_line":"                \"rel\": \"next\""},{"line_number":40,"context_line":"            },"},{"line_number":41,"context_line":"            {"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3a50d1a3_5f63d2b1","line":38,"in_reply_to":"3a50d1a3_09fe7c6b","updated":"2015-07-20 11:07:34.000000000","message":"Yes, I really agree. Pagination should be moved to the bottom.","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"721d4e7170144dcf44c22b2455f20dfbb178fe48","unresolved":false,"context_lines":[{"line_number":40,"context_line":"            },"},{"line_number":41,"context_line":"            {"},{"line_number":42,"context_line":"                \"href\": \"XXX?limit\u003d2\u0026marker\u003d\u003cfirst_item_uuid\u003e"},{"line_number":43,"context_line":"                         \u0026page_reverse\u003dTrue\","},{"line_number":44,"context_line":"                \"rel\": \"previous\""},{"line_number":45,"context_line":"            }"},{"line_number":46,"context_line":"        ],"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3a50d1a3_6994e036","line":43,"updated":"2015-07-20 10:33:25.000000000","message":"There is no need for page_reverse. The marker itself indicates the previous page\u0027s starting marker ID.","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"721d4e7170144dcf44c22b2455f20dfbb178fe48","unresolved":false,"context_lines":[{"line_number":80,"context_line":"            }"},{"line_number":81,"context_line":"        ],"},{"line_number":82,"context_line":"        ..."},{"line_number":83,"context_line":"    }"},{"line_number":84,"context_line":""},{"line_number":85,"context_line":"The following points are recommended:"},{"line_number":86,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"3a50d1a3_6965c043","line":83,"updated":"2015-07-20 10:33:25.000000000","message":"Instead of showing output for the first and last page link collections, you can just mention that a next link will only appear if there are more records than shown in the current page, and a previous link will only appear when there are records before the marker record in the current page.","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"721d4e7170144dcf44c22b2455f20dfbb178fe48","unresolved":false,"context_lines":[{"line_number":85,"context_line":"The following points are recommended:"},{"line_number":86,"context_line":""},{"line_number":87,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":88,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":89,"context_line":"- If \u0027marker\u0027 is not specified and \u0027page_reverse\u0027 is set to \u0027True\u0027, then no"},{"line_number":90,"context_line":"  items need to be returned."},{"line_number":91,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 400 with more"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3a50d1a3_89936cfa","line":88,"updated":"2015-07-20 10:33:25.000000000","message":"Probably worth mentioning that the maximum limit of records is configurable on a per-project basis?","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"721d4e7170144dcf44c22b2455f20dfbb178fe48","unresolved":false,"context_lines":[{"line_number":89,"context_line":"- If \u0027marker\u0027 is not specified and \u0027page_reverse\u0027 is set to \u0027True\u0027, then no"},{"line_number":90,"context_line":"  items need to be returned."},{"line_number":91,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 400 with more"},{"line_number":92,"context_line":"  detailed message."},{"line_number":93,"context_line":"- Negative limits are invalid, and it\u0027s not recommended to use a negative limit"},{"line_number":94,"context_line":"  to achieve the previous page."},{"line_number":95,"context_line":""}],"source_content_type":"text/x-rst","patch_set":5,"id":"3a50d1a3_2949f88b","line":92,"updated":"2015-07-20 10:33:25.000000000","message":"Arguably, this could be a 404 Not Found...","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"721d4e7170144dcf44c22b2455f20dfbb178fe48","unresolved":false,"context_lines":[{"line_number":91,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 400 with more"},{"line_number":92,"context_line":"  detailed message."},{"line_number":93,"context_line":"- Negative limits are invalid, and it\u0027s not recommended to use a negative limit"},{"line_number":94,"context_line":"  to achieve the previous page."},{"line_number":95,"context_line":""},{"line_number":96,"context_line":"Filtering"},{"line_number":97,"context_line":"---------"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3a50d1a3_e97470d0","line":94,"updated":"2015-07-20 10:33:25.000000000","message":"I would hold a line and say \"Negative limits are invalid and should result in a 400 Bad Request\"","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"fbe224ecaefd19db0486ec0f952968ca22b4ed32","unresolved":false,"context_lines":[{"line_number":91,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 400 with more"},{"line_number":92,"context_line":"  detailed message."},{"line_number":93,"context_line":"- Negative limits are invalid, and it\u0027s not recommended to use a negative limit"},{"line_number":94,"context_line":"  to achieve the previous page."},{"line_number":95,"context_line":""},{"line_number":96,"context_line":"Filtering"},{"line_number":97,"context_line":"---------"}],"source_content_type":"text/x-rst","patch_set":5,"id":"3a50d1a3_bf20d64a","line":94,"in_reply_to":"3a50d1a3_e97470d0","updated":"2015-07-20 11:07:34.000000000","message":"+1","commit_id":"c3ec69406cc47bc084ea9ee954f48736c9abb9f2"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"6b07be4965f3760d816680cc23780e00a1cc61fb","unresolved":false,"context_lines":[{"line_number":189,"context_line":"                \"rel\": \"next\""},{"line_number":190,"context_line":"            },"},{"line_number":191,"context_line":"            {"},{"line_number":192,"context_line":"                \"href\": \"/app?limit\u003d2\u0026marker\u003d\u003citem_before_previous_page\u003e\","},{"line_number":193,"context_line":"                \"rel\": \"previous\""},{"line_number":194,"context_line":"            }"},{"line_number":195,"context_line":"        ],"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_e7219b4e","line":192,"updated":"2015-07-21 19:19:46.000000000","message":"I think it makes more sense here to have a page defined as the first item on it. I don\u0027t feel too strongly about it, but it\u0027s what I\u0027ve seen in other APIs.","commit_id":"66b8bc8489996e08347840f589d8d8dfa320aa6d"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"bc31b3b516088ed52b99e43e06fe306e49abb03b","unresolved":false,"context_lines":[{"line_number":189,"context_line":"                \"rel\": \"next\""},{"line_number":190,"context_line":"            },"},{"line_number":191,"context_line":"            {"},{"line_number":192,"context_line":"                \"href\": \"/app?limit\u003d2\u0026marker\u003d\u003citem_before_previous_page\u003e\","},{"line_number":193,"context_line":"                \"rel\": \"previous\""},{"line_number":194,"context_line":"            }"},{"line_number":195,"context_line":"        ],"}],"source_content_type":"text/x-rst","patch_set":6,"id":"3a50d1a3_4cae6499","line":192,"in_reply_to":"3a50d1a3_e7219b4e","updated":"2015-07-22 04:00:20.000000000","message":"As far as I know, nova, neutron and cinder use the last item to reference the next link.\nhttps://github.com/openstack/nova/blob/master/nova/api/openstack/common.py#L467\nhttps://github.com/openstack/neutron/blob/master/neutron/api/api_common.py#L66\nNeutron implements previous page link using the first item of current page and the \u0027page_reverse\u0027 parameter.\nhttps://github.com/openstack/neutron/blob/master/neutron/api/v2/base.py#L231\nThe work flow of these projects is retrieving all the items in the current page, and then using the first item and the last item to generate the previous link and the next link.\nI think if we don\u0027t use page_reverse parameter, we need to change the workflow and use the first item to reference all the pages. Therefore, each page will have a unique link.","commit_id":"66b8bc8489996e08347840f589d8d8dfa320aa6d"},{"author":{"_account_id":6949,"name":"Bryan Davidson","email":"bryan.davidson@rackspace.com","username":"bryan-davidson"},"change_message_id":"be22468cd16c26f5861f8a69fd5143909da1e953","unresolved":false,"context_lines":[{"line_number":208,"context_line":"  page."},{"line_number":209,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":210,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":211,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 403 Not Found."},{"line_number":212,"context_line":"- Negative limits are invalid and should result in a 400 Bad Request."},{"line_number":213,"context_line":""},{"line_number":214,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":6,"id":"1a4dcd0f_86d77922","line":211,"updated":"2015-08-05 12:21:57.000000000","message":"Fix: 404 Not Found","commit_id":"66b8bc8489996e08347840f589d8d8dfa320aa6d"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"a66547887228fca7cfd532623089349cce6d4aea","unresolved":false,"context_lines":[{"line_number":164,"context_line":"request. To navigate the collection, the parameters \u0027limit\u0027 and \u0027marker\u0027"},{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the num of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a4dcd0f_fe33dd11","line":167,"updated":"2015-08-13 16:38:10.000000000","message":"s/num/number/ :)","commit_id":"6a4075a3a5b56e7e1949ae083987e96267476e73"},{"author":{"_account_id":6949,"name":"Bryan Davidson","email":"bryan.davidson@rackspace.com","username":"bryan-davidson"},"change_message_id":"693fd5b20724373143d6c965d1ac09f769b9f88f","unresolved":false,"context_lines":[{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"And the next previous page link and the next page link should be added to the"},{"line_number":172,"context_line":"\u0027_links\u0027 dict on the response for list operations."},{"line_number":173,"context_line":""},{"line_number":174,"context_line":"A example of requests:"}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a4dcd0f_e446eb7a","line":171,"updated":"2015-08-13 19:03:20.000000000","message":"Slight grammar improvement here: \"And the next previous page link and...\" to \"The previous page link and...\"","commit_id":"6a4075a3a5b56e7e1949ae083987e96267476e73"},{"author":{"_account_id":6949,"name":"Bryan Davidson","email":"bryan.davidson@rackspace.com","username":"bryan-davidson"},"change_message_id":"693fd5b20724373143d6c965d1ac09f769b9f88f","unresolved":false,"context_lines":[{"line_number":171,"context_line":"And the next previous page link and the next page link should be added to the"},{"line_number":172,"context_line":"\u0027_links\u0027 dict on the response for list operations."},{"line_number":173,"context_line":""},{"line_number":174,"context_line":"A example of requests:"},{"line_number":175,"context_line":""},{"line_number":176,"context_line":".. code::"},{"line_number":177,"context_line":""}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a4dcd0f_642adb92","line":174,"updated":"2015-08-13 19:03:20.000000000","message":"\"An example of a request\"?","commit_id":"6a4075a3a5b56e7e1949ae083987e96267476e73"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"a66547887228fca7cfd532623089349cce6d4aea","unresolved":false,"context_lines":[{"line_number":182,"context_line":""},{"line_number":183,"context_line":".. code::"},{"line_number":184,"context_line":""},{"line_number":185,"context_line":"    {"},{"line_number":186,"context_line":"        \"_links\": ["},{"line_number":187,"context_line":"            {"},{"line_number":188,"context_line":"                \"href\": \"/app?limit\u003d2\u0026marker\u003d\u003clast_item_of_current_page\u003e\","}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a4dcd0f_616652f0","line":185,"updated":"2015-08-13 16:38:10.000000000","message":"Would it be more illustrative if instead of /app? above, we use a collection resource and also include the collection resource in the response below?\n\nFor instance:\n\n .. code::\n\n    /items?limit\u003d2\u0026marker\u003d{uuid}\n\n.. code::\n\n    {\n        \"items\": [\n           ...\n        ],\n        \"_links\": [\n           ...\n        ]\n    }","commit_id":"6a4075a3a5b56e7e1949ae083987e96267476e73"},{"author":{"_account_id":6949,"name":"Bryan Davidson","email":"bryan.davidson@rackspace.com","username":"bryan-davidson"},"change_message_id":"693fd5b20724373143d6c965d1ac09f769b9f88f","unresolved":false,"context_lines":[{"line_number":182,"context_line":""},{"line_number":183,"context_line":".. code::"},{"line_number":184,"context_line":""},{"line_number":185,"context_line":"    {"},{"line_number":186,"context_line":"        \"_links\": ["},{"line_number":187,"context_line":"            {"},{"line_number":188,"context_line":"                \"href\": \"/app?limit\u003d2\u0026marker\u003d\u003clast_item_of_current_page\u003e\","}],"source_content_type":"text/x-rst","patch_set":7,"id":"1a4dcd0f_0772f9b0","line":185,"in_reply_to":"1a4dcd0f_616652f0","updated":"2015-08-13 19:03:20.000000000","message":"Agreed. The templating is nice - would it be more clear if we actually included some values for markers in the example?\n\nFor example, if in the request we provide 5 for {uuid}, items with ids 6 \u0026 7 in the response collection, and the appropriate 6 \u0026 7 UUIDs in the _links?","commit_id":"6a4075a3a5b56e7e1949ae083987e96267476e73"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"5770850b8e39c37a4455a028064a78df24a8ba79","unresolved":false,"context_lines":[{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"},{"line_number":172,"context_line":"dict on the response for list operations."},{"line_number":173,"context_line":""},{"line_number":174,"context_line":"A example of a request:"},{"line_number":175,"context_line":""},{"line_number":176,"context_line":".. code::"},{"line_number":177,"context_line":""}],"source_content_type":"text/x-rst","patch_set":8,"id":"1a4dcd0f_a6a2fa49","line":174,"updated":"2015-08-14 15:15:31.000000000","message":"s/A/An/","commit_id":"96d3768662864de6be6b6fedaf5681bcb1bda208"},{"author":{"_account_id":6949,"name":"Bryan Davidson","email":"bryan.davidson@rackspace.com","username":"bryan-davidson"},"change_message_id":"0e66bad2c188b1c273bcc987adb0a3ae1cbf282b","unresolved":false,"context_lines":[{"line_number":193,"context_line":"                \"baz\": \"honk\""},{"line_number":194,"context_line":"            }"},{"line_number":195,"context_line":"        ],"},{"line_number":196,"context_line":"        \"_links\": ["},{"line_number":197,"context_line":"            {"},{"line_number":198,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d\u003clast_item_of_current_page\u003e\","},{"line_number":199,"context_line":"                \"rel\": \"next\""}],"source_content_type":"text/x-rst","patch_set":9,"id":"fa1b9901_f4aaff84","line":196,"updated":"2015-08-17 21:59:16.000000000","message":"In a previous review [0], Jay Pipes mentions the JSON-HAL specification. How committed is the WG to that specification? If committed, we should change _links to a dictionary rather than a list.\n\nPersonally, I like that better because dictionaries are easier to programmatically access than lists! Thoughts?\n\n[0]: https://review.openstack.org/#/c/190743/5/guidelines/pagination_filter_sort.rst","commit_id":"4db8ad854d4c2704ef785b338ae8c7f6bb9a4e6a"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"b2b45860af8d9dd23a06a02b673e195aba189ba4","unresolved":false,"context_lines":[{"line_number":193,"context_line":"                \"baz\": \"honk\""},{"line_number":194,"context_line":"            }"},{"line_number":195,"context_line":"        ],"},{"line_number":196,"context_line":"        \"_links\": ["},{"line_number":197,"context_line":"            {"},{"line_number":198,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d\u003clast_item_of_current_page\u003e\","},{"line_number":199,"context_line":"                \"rel\": \"next\""}],"source_content_type":"text/x-rst","patch_set":9,"id":"fa1b9901_ddb0388e","line":196,"in_reply_to":"fa1b9901_d6e2609f","updated":"2015-08-18 03:01:56.000000000","message":"Jay, I have the same confusion with hal+json. If the ap-wg is commited, I think the response should be\n{\n    \"_links\": {\n        \"self\": { \"href\": \"...\"},\n        \"next\": { \"href\": \"...\"},\n        \"prev\": { \"href\": \"...\"},\n        \"find\": { \"href\": \"/items/{uuid}\", \"templated\": true}\n    },\n    \"_embedded\": {\n        \"items\": [\n            {...},\n            {...}\n        ]\n    }\n} \nAny suggestion about this?","commit_id":"4db8ad854d4c2704ef785b338ae8c7f6bb9a4e6a"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"cea47382c10ef5524c967dc272cb5100916b271a","unresolved":false,"context_lines":[{"line_number":193,"context_line":"                \"baz\": \"honk\""},{"line_number":194,"context_line":"            }"},{"line_number":195,"context_line":"        ],"},{"line_number":196,"context_line":"        \"_links\": ["},{"line_number":197,"context_line":"            {"},{"line_number":198,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d\u003clast_item_of_current_page\u003e\","},{"line_number":199,"context_line":"                \"rel\": \"next\""}],"source_content_type":"text/x-rst","patch_set":9,"id":"fa1b9901_c465ad45","line":196,"in_reply_to":"fa1b9901_ddb0388e","updated":"2015-08-18 11:51:06.000000000","message":"Just the _links part. No need to do the _embedded nesting, IMHO. Also, leave off the \"find\" link, since it\u0027s not germane to pagination.","commit_id":"4db8ad854d4c2704ef785b338ae8c7f6bb9a4e6a"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"b2b45860af8d9dd23a06a02b673e195aba189ba4","unresolved":false,"context_lines":[{"line_number":193,"context_line":"                \"baz\": \"honk\""},{"line_number":194,"context_line":"            }"},{"line_number":195,"context_line":"        ],"},{"line_number":196,"context_line":"        \"_links\": ["},{"line_number":197,"context_line":"            {"},{"line_number":198,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d\u003clast_item_of_current_page\u003e\","},{"line_number":199,"context_line":"                \"rel\": \"next\""}],"source_content_type":"text/x-rst","patch_set":9,"id":"fa1b9901_5d2668bb","line":196,"in_reply_to":"fa1b9901_f4aaff84","updated":"2015-08-18 03:01:56.000000000","message":"I agree with this from the implementation point of view. Thanks, Bryan.","commit_id":"4db8ad854d4c2704ef785b338ae8c7f6bb9a4e6a"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"5570f977c9418f5e6690b2a4dcdafc1e883fd072","unresolved":false,"context_lines":[{"line_number":193,"context_line":"                \"baz\": \"honk\""},{"line_number":194,"context_line":"            }"},{"line_number":195,"context_line":"        ],"},{"line_number":196,"context_line":"        \"_links\": ["},{"line_number":197,"context_line":"            {"},{"line_number":198,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d\u003clast_item_of_current_page\u003e\","},{"line_number":199,"context_line":"                \"rel\": \"next\""}],"source_content_type":"text/x-rst","patch_set":9,"id":"fa1b9901_d6e2609f","line":196,"in_reply_to":"fa1b9901_f4aaff84","updated":"2015-08-17 22:31:44.000000000","message":"Yeah, sorry, Bryan is correct. I was mistaken in the suggested output. It should be:\n\n \"_links\": {\n     \"next\": {\n         \"href\": \"...\",\n     },\n     \"prev\": {\n         \"href\": \"...\",\n     }\n }","commit_id":"4db8ad854d4c2704ef785b338ae8c7f6bb9a4e6a"},{"author":{"_account_id":15168,"name":"Kirill Zaitsev","email":"k.zaitsev@me.com","username":"kzaitsev"},"change_message_id":"6bdef7120dcec41bc62243c50b21dd2c31c34afa","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_ca928f9f","line":168,"updated":"2015-08-27 16:44:13.000000000","message":"I agree, that we should settle on how limit\u003d0 works. I\u0027d vote for limit\u003d0 meaning give me all (or maybe max_allowed)\n\nIf that\u0027s not the case — we should explicitly specify that it is impossible to get all items. and limit\u003d0 should return 400","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"0586a295e5a51d120638bc203eb0afcb8527e3fc","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_814562b4","line":168,"updated":"2015-08-27 16:03:01.000000000","message":"Ironic allows 0 meaning \"really all\" vs absent meaning \"internal maximum\". What do you recommend here?","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"3b3803f3906369f7245d2b9dc14ac2bee0186662","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_b269bb27","line":168,"in_reply_to":"ba15a1d1_2f99c81f","updated":"2015-09-15 15:21:09.000000000","message":"Okay, what if limit\u003d0 means zero and limit\u003dmax means the max_allowed. Leaving \u0027limit\u0027 off means all and it\u0027ll return 400 if that\u0027s impossible to get all items.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"30c60ac9e9aeedbc1ee62f417727c1ba5e156bea","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_fe361cb3","line":168,"in_reply_to":"ba15a1d1_43a9458f","updated":"2015-09-22 12:38:10.000000000","message":"No, limit\u003d0 returning zero results is definitely the wrong thing to do. If you want an optimized count call, that should be built, but optimizing limit\u003d0 to be count is mixing metaphors here, and hacking an API that will never be able to be made efficient that way.\n\nHonestly, limit should be required to be \u003e\u003d 1, limit\u003d0 would be a bad request.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":8099,"name":"Graham Hayes","email":"gr@ham.ie","username":"graham"},"change_message_id":"8a4004d54ff31fb72fb78400b1dde519ced6c01f","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_c8bfb4a8","line":168,"in_reply_to":"ba15a1d1_455b8df6","updated":"2015-09-16 14:27:39.000000000","message":"limit\u003d0 meaning zero is quite useful. for example we have a total_count metadata item that is returned in designate. limit\u003d0 would return 0 results, but would return the count.\n\nI think that a lot of projects may not be able to support all these guidelines, and not doing the right thing because some project can\u0027t implement it is a bad way to go.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"c64384cd2f957d160e4519741deb87bc1afba72f","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_5ca5f401","line":168,"in_reply_to":"ba15a1d1_49c5438c","updated":"2015-09-15 02:18:32.000000000","message":"I\u0027d prefer limit\u003d0 should be max allowed and I\u0027ll modify this.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":7973,"name":"Douglas Mendizábal","email":"dmendiza@redhat.com","username":"dougmendizabal"},"change_message_id":"3099672955c4bf85965e46e7b949b87cbac58418","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_2f99c81f","line":168,"in_reply_to":"ba15a1d1_5ca5f401","updated":"2015-09-15 15:05:41.000000000","message":"Please don\u0027t make limit\u003d0 anything other than zero.\n\nIf an explicit unlimited is needed I\u0027d prefer that it be something like limit\u003d-1","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"285a4711e0b36ad56089945ff86baf93d0757af8","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_455b8df6","line":168,"in_reply_to":"ba15a1d1_b269bb27","updated":"2015-09-16 13:55:03.000000000","message":"\u003e what if limit\u003d0 means zero \n\ndoesn\u0027t make any sense to me (and of course ironic would never adapt such guideline, as it would break too many users)","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"330e83b09853880ef76e4449c3ac973bfb08d74f","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_c504a47f","line":168,"in_reply_to":"ba15a1d1_bc4d0d74","updated":"2015-09-22 13:52:08.000000000","message":"It seems \"really\" difficult to reach an agreement on this. If so, I think the best way is making this configurable. If limit is not specified, the result will be max allowed by default. And admins can set \u0027max_allowed\u0027 to \u0027all\u0027, if it is possible to return all for the projects and potential risks are also considered acceptable to admins. And limit must be a positive integer.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":6773,"name":"Lucas Alvares Gomes","email":"lucasagomes@gmail.com","username":"lucasagomes"},"change_message_id":"13032fb106c8b25504de4e4a8a18c68c7c3aa4dc","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_0ff856c2","line":168,"in_reply_to":"ba15a1d1_c504a47f","updated":"2015-09-23 08:37:43.000000000","message":"Just to clarify, Ironic *do not* allow limit\u003d0 in the API [1], we only accept positive values. \n\nNow in the client we added this option to pass limit\u003d0; if you do pass limit\u003d0 to the client it will follow the pagination return all of the resources [2], this is done to facilitate the usage. That said, yes I agree that passing limit\u003d0 may not be the best way to express \"I want all resources\", but this is easy fixable.\n\n[1] https://github.com/openstack/ironic/blob/master/ironic/api/controllers/v1/utils.py#L45-L46\n\n[2] https://github.com/openstack/python-ironicclient/blob/52f4ba68ba8a2e45875783c3240fe58f27fa54c6/ironicclient/v1/node.py#L59-L66","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"fed44278dc1db75604aa4d9688a42b446c5dd1d7","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_43a9458f","line":168,"in_reply_to":"ba15a1d1_c8bfb4a8","updated":"2015-09-16 14:53:19.000000000","message":"Agreed.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"770df0ced4fd99540bca4b34fd418cd85c0592c7","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_bc4d0d74","line":168,"in_reply_to":"ba15a1d1_fe361cb3","updated":"2015-09-22 12:50:02.000000000","message":"Yeah, I agreed we don\u0027t really want limit\u003d0 to mean anything here.\n\nNot specifying a limit has to mean: return the max allowed\n\nHaving an option to return *all* is opening yourself up to DDoS attacks, in many cases. It depends how large the list can get, and how expensive it is to generate.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"e23f61e5b239054462e24952f710623bacecbe2b","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_67e36334","line":168,"in_reply_to":"da20952f_2a8786d8","updated":"2015-08-28 04:08:28.000000000","message":"limit\u003dmax is also good.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"67f0f7d34db87be8451c036b6a41d458783beb46","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_8dd79a22","line":168,"in_reply_to":"da20952f_346a641b","updated":"2015-08-28 15:17:28.000000000","message":"Leaving it off entirely should return some sensible default (probably not 10,000) number of results.\n\nI don\u0027t think that any caller not limiting their results should recieve the max supported by the datastore (or whatever other limiting factor).","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":177,"name":"Alex Meade","email":"mr.alex.meade@gmail.com","username":"alex-meade"},"change_message_id":"fc177bc907485931bc8deed69c248e571f04e466","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_346a641b","line":168,"in_reply_to":"da20952f_67e36334","updated":"2015-08-28 13:11:08.000000000","message":"I\u0027d prefer limit\u003d0 mean you get back 0. Any reason it can\u0027t just be left off entirely for the max allowed?","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":8099,"name":"Graham Hayes","email":"gr@ham.ie","username":"graham"},"change_message_id":"510cc15bfadb7eb85e0385d6e42681ad9ebcf969","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_2a8786d8","line":168,"in_reply_to":"da20952f_70a016a0","updated":"2015-08-27 18:32:27.000000000","message":"Definitely - in Designate we have a max page size set, as allowing people to list all records could be quite a large amount of load on the system. \n\nWe however use limit\u003dmax to indicate that they want the max size.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":10215,"name":"Peter Stachowski","email":"peter@tesora.com","username":"peterstac"},"change_message_id":"2362f7eeda65604cea163144e409c94ad00134f2","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_49c5438c","line":168,"in_reply_to":"da20952f_8dd79a22","updated":"2015-09-14 18:57:43.000000000","message":"I\u0027ve seen many cases where the idea of limit\u003d0 means return \u0027all\u0027 (where \u0027all\u0027 could map to \u0027max\u0027 if so documented), and I\u0027m ok with that.  (I\u0027ve also seen cases where it means \u0027return 0 rows,\u0027 but I think the usefulness of returning \u0027all\u0027 or \u0027max\u0027 seems better.)","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":2903,"name":"Morgan Fainberg","email":"morgan.fainberg@gmail.com","username":"mdrnstm"},"change_message_id":"d01304cc1ec82150e9d5bf2d59c544e41144b84f","unresolved":false,"context_lines":[{"line_number":165,"context_line":"can be set in the URI."},{"line_number":166,"context_line":""},{"line_number":167,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":168,"context_line":"         positive integer."},{"line_number":169,"context_line":"- marker: the ID of a reference item."},{"line_number":170,"context_line":""},{"line_number":171,"context_line":"The previous page link and the next page link should be added to the \u0027_links\u0027"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_70a016a0","line":168,"in_reply_to":"da20952f_ca928f9f","updated":"2015-08-27 17:31:43.000000000","message":"Please do not make limit\u003d0 explicitly mean \"all\". Some data stores have likits imposed beyond what openstack controlls. Limit\u003d0 should be \"max allowed\" wherever max allowed is enforced","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":330,"name":"John Dickinson","email":"me@not.mn","username":"notmyname"},"change_message_id":"0dec4156d460c9539ca0de33dd3d781bec347abb","unresolved":false,"context_lines":[{"line_number":198,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":199,"context_line":"            },"},{"line_number":200,"context_line":"            \"prev\": {"},{"line_number":201,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{item_before_previous_page}\""},{"line_number":202,"context_line":"            }"},{"line_number":203,"context_line":"        }"},{"line_number":204,"context_line":"    }"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_2196d6f0","line":201,"updated":"2015-08-27 16:06:07.000000000","message":"What is \"item_before_previous_page\"? Is it the \u003climit\u003enth item backwards in this list so that it returns the same size of page?\n\nI\u0027d prefer that the prev be dropped from this example. Only paginate forward.\n\nIf you want reverse pagination, use an end_marker construct. In that case, the \"next\" link has the end_marker as the first item in the current page.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"fed44278dc1db75604aa4d9688a42b446c5dd1d7","unresolved":false,"context_lines":[{"line_number":198,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":199,"context_line":"            },"},{"line_number":200,"context_line":"            \"prev\": {"},{"line_number":201,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{item_before_previous_page}\""},{"line_number":202,"context_line":"            }"},{"line_number":203,"context_line":"        }"},{"line_number":204,"context_line":"    }"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_fe97ce45","line":201,"in_reply_to":"ba15a1d1_3cdb607e","updated":"2015-09-16 14:53:19.000000000","message":"Any idea on previous page? Compared to leaving it off, I prefer adding another \"page_reverse\" parameter. Using the first item of current page as the end marker will make the previous page reversed. Further what if users want to get the previous page of the previous page.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":6773,"name":"Lucas Alvares Gomes","email":"lucasagomes@gmail.com","username":"lucasagomes"},"change_message_id":"21b1adb6823568088e08c5bafaf1312d328c1c2f","unresolved":false,"context_lines":[{"line_number":198,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":199,"context_line":"            },"},{"line_number":200,"context_line":"            \"prev\": {"},{"line_number":201,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{item_before_previous_page}\""},{"line_number":202,"context_line":"            }"},{"line_number":203,"context_line":"        }"},{"line_number":204,"context_line":"    }"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_af460abe","line":201,"in_reply_to":"ba15a1d1_fe97ce45","updated":"2015-09-23 08:55:32.000000000","message":"+1\n\nI agree with removing \"prev\", pagination should only go forward.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"c64384cd2f957d160e4519741deb87bc1afba72f","unresolved":false,"context_lines":[{"line_number":198,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":199,"context_line":"            },"},{"line_number":200,"context_line":"            \"prev\": {"},{"line_number":201,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{item_before_previous_page}\""},{"line_number":202,"context_line":"            }"},{"line_number":203,"context_line":"        }"},{"line_number":204,"context_line":"    }"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_3cdb607e","line":201,"in_reply_to":"da20952f_0d794a2f","updated":"2015-09-15 02:18:32.000000000","message":"I don\u0027t think it\u0027s a good idea to remove \"prev\". To be honest, it\u0027s useless if pagination is forward-only. And if \"item_before_previous_page\" is not friendly, we may just add another \"page_reverse\" parameter to reverse the sorting direction like the previous patch.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":8099,"name":"Graham Hayes","email":"gr@ham.ie","username":"graham"},"change_message_id":"723cead9278b59adfbe8d41a05c2f725b9381149","unresolved":false,"context_lines":[{"line_number":198,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":199,"context_line":"            },"},{"line_number":200,"context_line":"            \"prev\": {"},{"line_number":201,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{item_before_previous_page}\""},{"line_number":202,"context_line":"            }"},{"line_number":203,"context_line":"        }"},{"line_number":204,"context_line":"    }"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_caab6fd5","line":201,"in_reply_to":"da20952f_2196d6f0","updated":"2015-08-27 16:44:15.000000000","message":"How is this supposed to be tracked?\n\nTraditionally APIs that do marker and limit based pagination only supply \"next\", as it very difficult to generate a \"prev\" link efficiently.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"b079894094e46637d6d4d50dc01666c2c81fac57","unresolved":false,"context_lines":[{"line_number":198,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":199,"context_line":"            },"},{"line_number":200,"context_line":"            \"prev\": {"},{"line_number":201,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{item_before_previous_page}\""},{"line_number":202,"context_line":"            }"},{"line_number":203,"context_line":"        }"},{"line_number":204,"context_line":"    }"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_d508f42f","line":201,"in_reply_to":"da20952f_caab6fd5","updated":"2015-08-27 17:20:05.000000000","message":"Yeah, John and Graham really are correct here. Not sure what I was thinking originally. marker/limit is a forward-only pagination method...","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"67f0f7d34db87be8451c036b6a41d458783beb46","unresolved":false,"context_lines":[{"line_number":198,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":199,"context_line":"            },"},{"line_number":200,"context_line":"            \"prev\": {"},{"line_number":201,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{item_before_previous_page}\""},{"line_number":202,"context_line":"            }"},{"line_number":203,"context_line":"        }"},{"line_number":204,"context_line":"    }"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_0d794a2f","line":201,"in_reply_to":"da20952f_d508f42f","updated":"2015-08-28 15:17:28.000000000","message":"Agreed. Probably remove \"prev\" from the guideline.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":330,"name":"John Dickinson","email":"me@not.mn","username":"notmyname"},"change_message_id":"0dec4156d460c9539ca0de33dd3d781bec347abb","unresolved":false,"context_lines":[{"line_number":215,"context_line":"  page."},{"line_number":216,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":217,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":218,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":219,"context_line":"- Negative limits are invalid and should result in a 400 Bad Request."},{"line_number":220,"context_line":""},{"line_number":221,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_8116c2ef","line":218,"updated":"2015-08-27 16:06:07.000000000","message":"If a marker doesn\u0027t exist, it should NOT result in a 404. The marker is for \"everything after this point\".\n\nPlease do not require exact matches for markers.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":8099,"name":"Graham Hayes","email":"gr@ham.ie","username":"graham"},"change_message_id":"8a4004d54ff31fb72fb78400b1dde519ced6c01f","unresolved":false,"context_lines":[{"line_number":215,"context_line":"  page."},{"line_number":216,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":217,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":218,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":219,"context_line":"- Negative limits are invalid and should result in a 400 Bad Request."},{"line_number":220,"context_line":""},{"line_number":221,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_289d100a","line":218,"in_reply_to":"ba15a1d1_012dd7a6","updated":"2015-09-16 14:27:39.000000000","message":"it is called out above that the marker is an \"id\" not some random construct. \n\nif an ID doesn\u0027t exist how do you know where to start the page from? It should be a 404 with a message along the lines of  \"marker \u003cid\u003e not found\"","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"c64384cd2f957d160e4519741deb87bc1afba72f","unresolved":false,"context_lines":[{"line_number":215,"context_line":"  page."},{"line_number":216,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":217,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":218,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":219,"context_line":"- Negative limits are invalid and should result in a 400 Bad Request."},{"line_number":220,"context_line":""},{"line_number":221,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_012dd7a6","line":218,"in_reply_to":"ba15a1d1_291ecfba","updated":"2015-09-15 02:18:32.000000000","message":"I think the problem is which are the items after this one. The items are sorted according to the sorting parameters instead of marker. And if we just return all values \u003e\u003d marker to handle the case of a concurrent deleting marker, I don\u0027t think it is same to the result if the marker is not deleted.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":10215,"name":"Peter Stachowski","email":"peter@tesora.com","username":"peterstac"},"change_message_id":"2362f7eeda65604cea163144e409c94ad00134f2","unresolved":false,"context_lines":[{"line_number":215,"context_line":"  page."},{"line_number":216,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":217,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":218,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":219,"context_line":"- Negative limits are invalid and should result in a 400 Bad Request."},{"line_number":220,"context_line":""},{"line_number":221,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_291ecfba","line":218,"in_reply_to":"da20952f_083e18b8","updated":"2015-09-14 18:57:43.000000000","message":"I agree with this - having a \u0027missing marker\u0027 generate an error doesn\u0027t give a nice user experience.  Maybe the behaviour of the marker should be defined - i.e. list returns all values \u003e\u003d marker or all values \u003e marker (I believe the first is what Trove has implemented) instead of generating an error.  This would handle the case of someone else deleting a marker while you\u0027re navigating the list.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":330,"name":"John Dickinson","email":"me@not.mn","username":"notmyname"},"change_message_id":"37eec52e86222c16b25ed90a618a7761a3087d5b","unresolved":false,"context_lines":[{"line_number":215,"context_line":"  page."},{"line_number":216,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":217,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":218,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":219,"context_line":"- Negative limits are invalid and should result in a 400 Bad Request."},{"line_number":220,"context_line":""},{"line_number":221,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_083e18b8","line":218,"in_reply_to":"da20952f_74ba1c70","updated":"2015-08-28 15:28:29.000000000","message":"Yes, pagination should continue to work. A marker is for \"everything after this one\", and it doesn\u0027t matter if the given marker value exists or not.\n\nSuppose you are storing year/month/day named things, and you want to get back a list of stuff for a given month. Instead of needing to find the last element in the previous month, simply give a marker of \"year/month/\" and you\u0027ll get all the data that\u0027s in and after that month, up to the limit.\n\nRequiring the marker to exist limit functionality and makes the user experience harder.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":15168,"name":"Kirill Zaitsev","email":"k.zaitsev@me.com","username":"kzaitsev"},"change_message_id":"6bdef7120dcec41bc62243c50b21dd2c31c34afa","unresolved":false,"context_lines":[{"line_number":215,"context_line":"  page."},{"line_number":216,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":217,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":218,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":219,"context_line":"- Negative limits are invalid and should result in a 400 Bad Request."},{"line_number":220,"context_line":""},{"line_number":221,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_4a519f0d","line":218,"in_reply_to":"da20952f_8116c2ef","updated":"2015-08-27 16:44:13.000000000","message":"I have to agree, that 404 doesn\u0027t feel appropriate here. it would mean, that \"there are no items below this item\". While what we really mean is that \"we do not know if there are packages below this item, cause item is malformed\".\na 400 feels more appropriate","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":8099,"name":"Graham Hayes","email":"gr@ham.ie","username":"graham"},"change_message_id":"723cead9278b59adfbe8d41a05c2f725b9381149","unresolved":false,"context_lines":[{"line_number":215,"context_line":"  page."},{"line_number":216,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":217,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":218,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":219,"context_line":"- Negative limits are invalid and should result in a 400 Bad Request."},{"line_number":220,"context_line":""},{"line_number":221,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_aa971b8f","line":218,"in_reply_to":"da20952f_8116c2ef","updated":"2015-08-27 16:44:15.000000000","message":"it should be an ID - the correct response is a 404 if it does not exist.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":177,"name":"Alex Meade","email":"mr.alex.meade@gmail.com","username":"alex-meade"},"change_message_id":"fc177bc907485931bc8deed69c248e571f04e466","unresolved":false,"context_lines":[{"line_number":215,"context_line":"  page."},{"line_number":216,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":217,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":218,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":219,"context_line":"- Negative limits are invalid and should result in a 400 Bad Request."},{"line_number":220,"context_line":""},{"line_number":221,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_74ba1c70","line":218,"in_reply_to":"da20952f_aa971b8f","updated":"2015-08-28 13:11:08.000000000","message":"It\u0027s not a 404 because the resource you are requesting still exists. I\u0027d say a 400 makes sense here to let them know they made a mistake (but what about a deleted marker? should pagination continue to work?)","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":330,"name":"John Dickinson","email":"me@not.mn","username":"notmyname"},"change_message_id":"0dec4156d460c9539ca0de33dd3d781bec347abb","unresolved":false,"context_lines":[{"line_number":217,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":218,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":219,"context_line":"- Negative limits are invalid and should result in a 400 Bad Request."},{"line_number":220,"context_line":""},{"line_number":221,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"},{"line_number":222,"context_line":".. [2] http://specs.openstack.org/openstack/neutron-specs/specs/api/"},{"line_number":223,"context_line":"       networking_general_api_information.html#pagination"}],"source_content_type":"text/x-rst","patch_set":10,"id":"da20952f_e1fe9e6a","line":220,"updated":"2015-08-27 16:06:07.000000000","message":"Something should be added along the lines of:\n\n\"it\u0027s ok to return less than \u003climit\u003e number of responses. A user knows they are at the end of a the list of pages when there are no more _links\"\n\nThis is something that we don\u0027t do in Swift, but experience has shown is important for future scalability.","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":10215,"name":"Peter Stachowski","email":"peter@tesora.com","username":"peterstac"},"change_message_id":"2362f7eeda65604cea163144e409c94ad00134f2","unresolved":false,"context_lines":[{"line_number":217,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":218,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":219,"context_line":"- Negative limits are invalid and should result in a 400 Bad Request."},{"line_number":220,"context_line":""},{"line_number":221,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"},{"line_number":222,"context_line":".. [2] http://specs.openstack.org/openstack/neutron-specs/specs/api/"},{"line_number":223,"context_line":"       networking_general_api_information.html#pagination"}],"source_content_type":"text/x-rst","patch_set":10,"id":"ba15a1d1_e98d3732","line":220,"in_reply_to":"da20952f_e1fe9e6a","updated":"2015-09-14 18:57:43.000000000","message":"Note that the first point in the list addresses this issue","commit_id":"2270502297b229908bc099f862457726ba5a0756"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"f071b8a6ec2f8f8e28d93c7c4c55413fc52a644c","unresolved":false,"context_lines":[{"line_number":159,"context_line":"Pagination"},{"line_number":160,"context_line":"----------"},{"line_number":161,"context_line":""},{"line_number":162,"context_line":"Many projects have implemented pagination for list operations, see [2]_."},{"line_number":163,"context_line":"Pagination supports returning a maximum number of items in a single HTTP"},{"line_number":164,"context_line":"request. To navigate the collection, the parameters \u0027limit\u0027 and \u0027marker\u0027"},{"line_number":165,"context_line":"can be set in the URI."}],"source_content_type":"text/x-rst","patch_set":12,"id":"da85f559_3cceceb4","line":162,"updated":"2015-11-10 15:52:54.000000000","message":"i\u0027m not sure we need this line, but if we keep it i think it should be more specific about the reference link. since the reference is really just showing neutron\u0027s implementation, i think it should read:\n\n\"Many projects have implemented pagination for list operations, for example see neutron\u0027s implementation [2]_.\"","commit_id":"83e892a8d01154e263c887eab41a24ef39f540c3"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"f071b8a6ec2f8f8e28d93c7c4c55413fc52a644c","unresolved":false,"context_lines":[{"line_number":202,"context_line":""},{"line_number":203,"context_line":"Note that, \u0027marker\u0027 and \u0027limit\u0027 are optional. By default, if \u0027marker\u0027 is not"},{"line_number":204,"context_line":"set, the response will be the first page. And if \u0027limit\u0027 is not set, the number"},{"line_number":205,"context_line":"of items returned respect the maximum allowed. Both sorting and filtering"},{"line_number":206,"context_line":"parameters could also be included in the url."},{"line_number":207,"context_line":""},{"line_number":208,"context_line":"The following points are recommended:"}],"source_content_type":"text/x-rst","patch_set":12,"id":"da85f559_dc21c24e","line":205,"updated":"2015-11-10 15:52:54.000000000","message":"i think this could be a little clearer as:\n\n\"And if \u0027limit\u0027 is not set, the number of items returned will be the maximum allowed.\"","commit_id":"83e892a8d01154e263c887eab41a24ef39f540c3"},{"author":{"_account_id":6873,"name":"Matt Riedemann","email":"mriedem.os@gmail.com","username":"mriedem"},"change_message_id":"d803a2326f7b09705fcaab455f73f8199dbc7073","unresolved":false,"context_lines":[{"line_number":201,"context_line":""},{"line_number":202,"context_line":"Note that, \u0027marker\u0027 and \u0027limit\u0027 are optional. By default, if \u0027marker\u0027 is not"},{"line_number":203,"context_line":"set, the response will be the first page. And if \u0027limit\u0027 is not set, the number"},{"line_number":204,"context_line":"of items returned will be the maximum allowed. Both sorting and filtering"},{"line_number":205,"context_line":"parameters could also be included in the url."},{"line_number":206,"context_line":""},{"line_number":207,"context_line":"The following points are recommended:"}],"source_content_type":"text/x-rst","patch_set":13,"id":"ba8a016a_bf968e92","line":204,"updated":"2015-11-16 16:58:12.000000000","message":"\"items returned will be the maximum allowed\" - maybe note that this is generally controlled via config option, e.g.:\n\nhttps://github.com/openstack/nova/blob/master/nova/api/openstack/common.py#L42-L45","commit_id":"315fd8cc901f90aa1805ca60fc5531eee093a66a"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"567f9b188aaecd1f378ebb18ad1573e675e67fcf","unresolved":false,"context_lines":[{"line_number":201,"context_line":""},{"line_number":202,"context_line":"Note that, \u0027marker\u0027 and \u0027limit\u0027 are optional. By default, if \u0027marker\u0027 is not"},{"line_number":203,"context_line":"set, the response will be the first page. And if \u0027limit\u0027 is not set, the number"},{"line_number":204,"context_line":"of items returned will be the maximum allowed. Both sorting and filtering"},{"line_number":205,"context_line":"parameters could also be included in the url."},{"line_number":206,"context_line":""},{"line_number":207,"context_line":"The following points are recommended:"}],"source_content_type":"text/x-rst","patch_set":13,"id":"ba8a016a_92cfe6af","line":204,"in_reply_to":"ba8a016a_bf968e92","updated":"2015-11-17 03:25:04.000000000","message":"done","commit_id":"315fd8cc901f90aa1805ca60fc5531eee093a66a"},{"author":{"_account_id":330,"name":"John Dickinson","email":"me@not.mn","username":"notmyname"},"change_message_id":"94bf0c1a0556f2ba11bbfdb427d1112476b9d3b7","unresolved":false,"context_lines":[{"line_number":210,"context_line":"  the current page."},{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":213,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":214,"context_line":"- If limit \u003c\u003d 0, it will result in a 400 Bad Request."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":13,"id":"da85f559_95afd293","line":213,"updated":"2015-11-13 17:43:57.000000000","message":"I still think this is a bad idea. It makes common use cases harder.\n\nFor example:\n\nstoring logs as year/month/day/hour/loghash.log\n\nFind all of the logs from the last 3 days. If a marker must exist to be specified, then I need to find all the logs that are there, find the last one before the range of what I\u0027m looking for, then do another marker query (but I just got all the items in order to find the marker, so what does doing a marker request even gain for me?).\n\nFurthermore, if a marker must exist, and as defined in line 197 the marker is the last item of the current page, then it\u0027s impossible to do a marker request that gets the very first item in the set.\n\nIf a marker isn\u0027t required to be in the set, then I can request the list with a marker of the first year/month/day I\u0027m looking for, and I get back what I\u0027m looking for and the service did all the hard work.\n\nI\u0027d much prefer to define marker as \"return stuff that comes after the marker\" rather than \"the first item that exists before the result set\" or \"the first item in the result set\".\n\nAlso, for point of reference, the current Swift implementation of marker does not require the marker to exist in the set of paged items.","commit_id":"315fd8cc901f90aa1805ca60fc5531eee093a66a"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"48a722852c412ad05955d3f2a2a5e174f9ede472","unresolved":false,"context_lines":[{"line_number":210,"context_line":"  the current page."},{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":213,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":214,"context_line":"- If limit \u003c\u003d 0, it will result in a 400 Bad Request."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":13,"id":"ba8a016a_824ed1bf","line":213,"in_reply_to":"ba8a016a_31797894","updated":"2015-11-16 17:23:13.000000000","message":"I think we need to distinguish limit / marker from other generic search parameters. Limit / marker is about starting with a set of results, and getting a marker back to get the next batch. If a project wants to implement other kinds of searching beyond this, like in the swift case, I don\u0027t think it\u0027s in conflict with this.\n\nIs the concern that swift uses marker as a key word already for non pagination workflows?","commit_id":"315fd8cc901f90aa1805ca60fc5531eee093a66a"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"567f9b188aaecd1f378ebb18ad1573e675e67fcf","unresolved":false,"context_lines":[{"line_number":210,"context_line":"  the current page."},{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":213,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":214,"context_line":"- If limit \u003c\u003d 0, it will result in a 400 Bad Request."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":13,"id":"ba8a016a_61f716d4","line":213,"in_reply_to":"ba8a016a_824ed1bf","updated":"2015-11-17 03:25:04.000000000","message":"I got a mistake here. But I agree with Sean. Distinguishing marker in pagination from other search parameters seems more reasonable.","commit_id":"315fd8cc901f90aa1805ca60fc5531eee093a66a"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"26c56ea156f61ecd74a11da4bfc318850a050c0e","unresolved":false,"context_lines":[{"line_number":210,"context_line":"  the current page."},{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":213,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":214,"context_line":"- If limit \u003c\u003d 0, it will result in a 400 Bad Request."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":13,"id":"ba8a016a_43199d87","line":213,"in_reply_to":"ba8a016a_824ed1bf","updated":"2015-11-17 13:44:52.000000000","message":"The difference is whether the marker is part of an ordered sequence, where the marker is interpreted as \"don\u0027t give me anything with a value less than this\". Examples of this would be sets ordered by integer IDs or alphabetical names. In this case, if the marker doesn\u0027t exist, a 404 would not be appropriate. In the other case, where the marker is something without an inherent order, such as UUIDs, finding the item with that value is critical, so a 404 would definitely be appropriate.","commit_id":"315fd8cc901f90aa1805ca60fc5531eee093a66a"},{"author":{"_account_id":177,"name":"Alex Meade","email":"mr.alex.meade@gmail.com","username":"alex-meade"},"change_message_id":"d20d92df4a6685e4426fe9d5abec159292439821","unresolved":false,"context_lines":[{"line_number":210,"context_line":"  the current page."},{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":213,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":214,"context_line":"- If limit \u003c\u003d 0, it will result in a 400 Bad Request."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":13,"id":"ba8a016a_31797894","line":213,"in_reply_to":"da85f559_06fe436b","updated":"2015-11-16 15:37:48.000000000","message":"I definitely don\u0027t think this should be a 404 but I don\u0027t have a great alternative to silently ignoring marker if it\u0027s not found.","commit_id":"315fd8cc901f90aa1805ca60fc5531eee093a66a"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"581e20f5e4a75ef3e18baa6f6a2f17905b7fd740","unresolved":false,"context_lines":[{"line_number":210,"context_line":"  the current page."},{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":213,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":214,"context_line":"- If limit \u003c\u003d 0, it will result in a 400 Bad Request."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":13,"id":"da85f559_9d25abc3","line":213,"in_reply_to":"da85f559_95afd293","updated":"2015-11-14 03:28:06.000000000","message":"@Jonh Dickinson, I think marker is not something like date with some kind of order, it\u0027s just a random uuid.\nFurther, as sorting is also optional here, what\u0027s the proper result of \u0027/items?marker\u003d{non-exist_uuid}\u0026sort\u003dcreated_at\u0027?\nAnd if we want to get the first page of items, we can just specify the \u0027limit\u0027.","commit_id":"315fd8cc901f90aa1805ca60fc5531eee093a66a"},{"author":{"_account_id":330,"name":"John Dickinson","email":"me@not.mn","username":"notmyname"},"change_message_id":"360682bb7bab76a45592be9706a2715b096fcc88","unresolved":false,"context_lines":[{"line_number":210,"context_line":"  the current page."},{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":213,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":214,"context_line":"- If limit \u003c\u003d 0, it will result in a 400 Bad Request."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":13,"id":"da85f559_06fe436b","line":213,"in_reply_to":"da85f559_9d25abc3","updated":"2015-11-14 16:49:54.000000000","message":"The marker can have different definitions depending on the primary id of whatever is being paginated over. So with nova it might be a uuid4 (a \"random uuid\") for each instance. But for swift, the unique identifier is the object name. And for other projects it may be something else.\n\nI\u0027m not sure of the best answer to your question. One idea would be to say that the marker is based on the sort field given (defaulting to the primary id if not given). So in this case, if created_at is the sort field, then the marker would be interpreted as a created_at value. That would allow for consistent pages of results to be returned.","commit_id":"315fd8cc901f90aa1805ca60fc5531eee093a66a"},{"author":{"_account_id":15888,"name":"Zhenyu Zheng","email":"zheng.zhenyu@outlook.com","username":"Kevin_Zheng"},"change_message_id":"3b32b2d4240c3884165a4f26c5742e9f0d8532c7","unresolved":false,"context_lines":[{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":213,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":214,"context_line":"- If limit \u003c\u003d 0, it will result in a 400 Bad Request."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":13,"id":"da85f559_6f1ebf60","line":214,"updated":"2015-11-11 01:06:17.000000000","message":"So have we decided on this?","commit_id":"315fd8cc901f90aa1805ca60fc5531eee093a66a"},{"author":{"_account_id":15888,"name":"Zhenyu Zheng","email":"zheng.zhenyu@outlook.com","username":"Kevin_Zheng"},"change_message_id":"b8d20f8a1768b75aac902ab24141a3fecbe5f7de","unresolved":false,"context_lines":[{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":213,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":214,"context_line":"- If limit \u003c\u003d 0, it will result in a 400 Bad Request."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":13,"id":"da85f559_d9b4d583","line":214,"in_reply_to":"da85f559_46e2af30","updated":"2015-11-13 06:58:58.000000000","message":"@Michael McCune, it\u0027s also good for me, happy to see that we have finally dicide on this.","commit_id":"315fd8cc901f90aa1805ca60fc5531eee093a66a"},{"author":{"_account_id":12321,"name":"Ryan Brown","email":"rybrown@redhat.com","username":"ryansb"},"change_message_id":"d1d92c6befd8f34f27c53ea013421d54014669f1","unresolved":false,"context_lines":[{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":213,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":214,"context_line":"- If limit \u003c\u003d 0, it will result in a 400 Bad Request."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":13,"id":"da85f559_a6383bef","line":214,"in_reply_to":"da85f559_46e2af30","updated":"2015-11-11 13:54:37.000000000","message":"A 400 is definitely the way to go here. Asking for a list of zero length is nonsense, as is asking for a list with -10 items.","commit_id":"315fd8cc901f90aa1805ca60fc5531eee093a66a"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"4b80aaf1be3799a599a17ca72dc3eaa9ac0803ae","unresolved":false,"context_lines":[{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":213,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."},{"line_number":214,"context_line":"- If limit \u003c\u003d 0, it will result in a 400 Bad Request."},{"line_number":215,"context_line":""},{"line_number":216,"context_line":".. [1] https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Sorting"}],"source_content_type":"text/x-rst","patch_set":13,"id":"da85f559_46e2af30","line":214,"in_reply_to":"da85f559_6f1ebf60","updated":"2015-11-11 13:41:33.000000000","message":"it seems reasonable to me, did you have objections?","commit_id":"315fd8cc901f90aa1805ca60fc5531eee093a66a"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"7adbd2df6a15142e1f4ef1a3ab8a9d8ed4b3ddba","unresolved":false,"context_lines":[{"line_number":159,"context_line":"----------"},{"line_number":160,"context_line":""},{"line_number":161,"context_line":"Pagination supports returning a maximum number of items in a single HTTP"},{"line_number":162,"context_line":"request. To navigate the collection, the parameters \u0027limit\u0027 and \u0027marker\u0027 can"},{"line_number":163,"context_line":"be set in the URI."},{"line_number":164,"context_line":""},{"line_number":165,"context_line":"- limit: determine the number of items on the response, which should be a"}],"source_content_type":"text/x-rst","patch_set":14,"id":"ba8a016a_ef8016f9","line":162,"updated":"2015-11-20 00:04:33.000000000","message":"s/request/response/ ?","commit_id":"7e3cf5a38962c020f1a0d4b6f6feb05a33b4aa79"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"8f4f738853bfee37c60ed5bce7a97a8e78791041","unresolved":false,"context_lines":[{"line_number":159,"context_line":"----------"},{"line_number":160,"context_line":""},{"line_number":161,"context_line":"Pagination supports returning a maximum number of items in a single HTTP"},{"line_number":162,"context_line":"request. To navigate the collection, the parameters \u0027limit\u0027 and \u0027marker\u0027 can"},{"line_number":163,"context_line":"be set in the URI."},{"line_number":164,"context_line":""},{"line_number":165,"context_line":"- limit: determine the number of items on the response, which should be a"}],"source_content_type":"text/x-rst","patch_set":14,"id":"ba8a016a_ecb7bd82","line":162,"in_reply_to":"ba8a016a_ef8016f9","updated":"2015-11-20 03:02:44.000000000","message":"Done.","commit_id":"7e3cf5a38962c020f1a0d4b6f6feb05a33b4aa79"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"7adbd2df6a15142e1f4ef1a3ab8a9d8ed4b3ddba","unresolved":false,"context_lines":[{"line_number":191,"context_line":"                \"baz\": \"honk\""},{"line_number":192,"context_line":"            }"},{"line_number":193,"context_line":"        ],"},{"line_number":194,"context_line":"        \"_links\": {"},{"line_number":195,"context_line":"            \"next\": {"},{"line_number":196,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":197,"context_line":"            }"}],"source_content_type":"text/x-rst","patch_set":14,"id":"ba8a016a_8a5cd819","line":194,"updated":"2015-11-20 00:04:33.000000000","message":"Why cannot we use \"links\" without \"_\"?\nThe prefix \"_\" seems to contain some meaning, so it is very nice to contain the reason in the guideline.","commit_id":"7e3cf5a38962c020f1a0d4b6f6feb05a33b4aa79"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"8f4f738853bfee37c60ed5bce7a97a8e78791041","unresolved":false,"context_lines":[{"line_number":191,"context_line":"                \"baz\": \"honk\""},{"line_number":192,"context_line":"            }"},{"line_number":193,"context_line":"        ],"},{"line_number":194,"context_line":"        \"_links\": {"},{"line_number":195,"context_line":"            \"next\": {"},{"line_number":196,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":197,"context_line":"            }"}],"source_content_type":"text/x-rst","patch_set":14,"id":"ba8a016a_acae952b","line":194,"in_reply_to":"ba8a016a_8a5cd819","updated":"2015-11-20 03:02:44.000000000","message":"+1. done.","commit_id":"7e3cf5a38962c020f1a0d4b6f6feb05a33b4aa79"},{"author":{"_account_id":7,"name":"Jay Pipes","email":"jaypipes@gmail.com","username":"jaypipes"},"change_message_id":"266da1f67740b4623fcedb97b8a7b422d672fc15","unresolved":false,"context_lines":[{"line_number":191,"context_line":"                \"baz\": \"honk\""},{"line_number":192,"context_line":"            }"},{"line_number":193,"context_line":"        ],"},{"line_number":194,"context_line":"        \"_links\": {"},{"line_number":195,"context_line":"            \"next\": {"},{"line_number":196,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":197,"context_line":"            }"}],"source_content_type":"text/x-rst","patch_set":14,"id":"ba8a016a_0fe0f3cb","line":194,"in_reply_to":"ba8a016a_8a5cd819","updated":"2015-11-20 03:18:29.000000000","message":"The _links format is from JSON+HAL specification, which I asked wuhao to use:\n\nhttps://tools.ietf.org/html/draft-kelly-json-hal-07#section-5","commit_id":"7e3cf5a38962c020f1a0d4b6f6feb05a33b4aa79"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"7adbd2df6a15142e1f4ef1a3ab8a9d8ed4b3ddba","unresolved":false,"context_lines":[{"line_number":201,"context_line":"Note that, \u0027marker\u0027 and \u0027limit\u0027 are optional. By default, if \u0027marker\u0027 is not"},{"line_number":202,"context_line":"set, the response will be the first page. And if \u0027limit\u0027 is not set, the number"},{"line_number":203,"context_line":"of items returned will be the maximum allowed, and this is generally controlled"},{"line_number":204,"context_line":"via config options. Sorting and filtering parameters could also be specified"},{"line_number":205,"context_line":"in the url."},{"line_number":206,"context_line":""},{"line_number":207,"context_line":"The following points are recommended:"}],"source_content_type":"text/x-rst","patch_set":14,"id":"ba8a016a_afd44eeb","line":204,"updated":"2015-11-20 00:04:33.000000000","message":"I am imaging this \"config options\" are server side, right?","commit_id":"7e3cf5a38962c020f1a0d4b6f6feb05a33b4aa79"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"8f4f738853bfee37c60ed5bce7a97a8e78791041","unresolved":false,"context_lines":[{"line_number":201,"context_line":"Note that, \u0027marker\u0027 and \u0027limit\u0027 are optional. By default, if \u0027marker\u0027 is not"},{"line_number":202,"context_line":"set, the response will be the first page. And if \u0027limit\u0027 is not set, the number"},{"line_number":203,"context_line":"of items returned will be the maximum allowed, and this is generally controlled"},{"line_number":204,"context_line":"via config options. Sorting and filtering parameters could also be specified"},{"line_number":205,"context_line":"in the url."},{"line_number":206,"context_line":""},{"line_number":207,"context_line":"The following points are recommended:"}],"source_content_type":"text/x-rst","patch_set":14,"id":"ba8a016a_6cf66d5e","line":204,"in_reply_to":"ba8a016a_afd44eeb","updated":"2015-11-20 03:02:44.000000000","message":"Yes.","commit_id":"7e3cf5a38962c020f1a0d4b6f6feb05a33b4aa79"},{"author":{"_account_id":6167,"name":"Ken\u0027ichi Ohmichi","email":"ken1ohmichi@gmail.com","username":"oomichi"},"change_message_id":"7adbd2df6a15142e1f4ef1a3ab8a9d8ed4b3ddba","unresolved":false,"context_lines":[{"line_number":206,"context_line":""},{"line_number":207,"context_line":"The following points are recommended:"},{"line_number":208,"context_line":""},{"line_number":209,"context_line":"- The next page link will only appear if there are more records than shown in"},{"line_number":210,"context_line":"  the current page."},{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."}],"source_content_type":"text/x-rst","patch_set":14,"id":"ba8a016a_8f8dcad4","line":209,"updated":"2015-11-20 00:04:33.000000000","message":"Does \"The next page link\" mean \"_links\" or \"next\"?\n\ne.g:\n\n {\n     \"items\": [\n         ...\n     ]\n }\n\nor\n\n {\n     \"items\": [\n         ...\n     ],\n     \"_links\": null\n }\n\n?","commit_id":"7e3cf5a38962c020f1a0d4b6f6feb05a33b4aa79"},{"author":{"_account_id":14976,"name":"wuhao","email":"wuhao@unitedstack.com","username":"wuhao"},"change_message_id":"8f4f738853bfee37c60ed5bce7a97a8e78791041","unresolved":false,"context_lines":[{"line_number":206,"context_line":""},{"line_number":207,"context_line":"The following points are recommended:"},{"line_number":208,"context_line":""},{"line_number":209,"context_line":"- The next page link will only appear if there are more records than shown in"},{"line_number":210,"context_line":"  the current page."},{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."}],"source_content_type":"text/x-rst","patch_set":14,"id":"ba8a016a_6c7bcdbe","line":209,"in_reply_to":"ba8a016a_8f8dcad4","updated":"2015-11-20 03:02:44.000000000","message":"For extensibility, I think Removing \"next\" is more reasonable here.","commit_id":"7e3cf5a38962c020f1a0d4b6f6feb05a33b4aa79"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"5d361efdd205446007d164a3e180affa6bc52c55","unresolved":false,"context_lines":[{"line_number":191,"context_line":"                \"baz\": \"honk\""},{"line_number":192,"context_line":"            }"},{"line_number":193,"context_line":"        ],"},{"line_number":194,"context_line":"        \"_links\": {"},{"line_number":195,"context_line":"            \"next\": {"},{"line_number":196,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":197,"context_line":"            }"}],"source_content_type":"text/x-rst","patch_set":15,"id":"9a8ffd7b_802fada0","line":194,"updated":"2015-11-24 17:46:04.000000000","message":"Do we know what services already use this approach?\n\nCertainly Nova seems to have gone for the list of rel/hrefs that seems to more head towards:\nhttp://json-schema.org/latest/json-schema-hypermedia.html#anchor17\n\nIts not miles away from this, just:\n\n\"links\": [\n{\"rel\": \"next\", \"href\": \"xxxx\"} \n]","commit_id":"c1a05289c5b4327e5321d5c6882fe677df2f0d2d"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"3ec3c5f9b822d6f37201c2247eaf7e6af676622e","unresolved":false,"context_lines":[{"line_number":191,"context_line":"                \"baz\": \"honk\""},{"line_number":192,"context_line":"            }"},{"line_number":193,"context_line":"        ],"},{"line_number":194,"context_line":"        \"_links\": {"},{"line_number":195,"context_line":"            \"next\": {"},{"line_number":196,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":197,"context_line":"            }"}],"source_content_type":"text/x-rst","patch_set":15,"id":"9a8ffd7b_a9243160","line":194,"in_reply_to":"9a8ffd7b_4d643a21","updated":"2015-11-30 14:29:07.000000000","message":"if everything out there uses a list, is there a reason we\u0027re changing that?","commit_id":"c1a05289c5b4327e5321d5c6882fe677df2f0d2d"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"388326c890e5e4a45dcc6c6fe756c66e16946b07","unresolved":false,"context_lines":[{"line_number":191,"context_line":"                \"baz\": \"honk\""},{"line_number":192,"context_line":"            }"},{"line_number":193,"context_line":"        ],"},{"line_number":194,"context_line":"        \"_links\": {"},{"line_number":195,"context_line":"            \"next\": {"},{"line_number":196,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":197,"context_line":"            }"}],"source_content_type":"text/x-rst","patch_set":15,"id":"9a8ffd7b_ba76913c","line":194,"in_reply_to":"9a8ffd7b_802fada0","updated":"2015-11-24 21:09:16.000000000","message":"IIRC ironic is using the same approach as nova","commit_id":"c1a05289c5b4327e5321d5c6882fe677df2f0d2d"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"7973cab4d2b8caba5e421d58cf65db4216b574bb","unresolved":false,"context_lines":[{"line_number":191,"context_line":"                \"baz\": \"honk\""},{"line_number":192,"context_line":"            }"},{"line_number":193,"context_line":"        ],"},{"line_number":194,"context_line":"        \"_links\": {"},{"line_number":195,"context_line":"            \"next\": {"},{"line_number":196,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":197,"context_line":"            }"}],"source_content_type":"text/x-rst","patch_set":15,"id":"9a8ffd7b_52b1e0de","line":194,"in_reply_to":"9a8ffd7b_a9243160","updated":"2015-12-03 14:35:00.000000000","message":"pretty much what I thought as well.\nI am probably missing some context, though","commit_id":"c1a05289c5b4327e5321d5c6882fe677df2f0d2d"},{"author":{"_account_id":8846,"name":"Hao Wang","display_name":"Hao Wang","email":"sxmatch1986@gmail.com","username":"sxmatch"},"change_message_id":"0c6a3054fc7d7df11e93971a3bfd97f1b965cc17","unresolved":false,"context_lines":[{"line_number":191,"context_line":"                \"baz\": \"honk\""},{"line_number":192,"context_line":"            }"},{"line_number":193,"context_line":"        ],"},{"line_number":194,"context_line":"        \"_links\": {"},{"line_number":195,"context_line":"            \"next\": {"},{"line_number":196,"context_line":"                \"href\": \"/items?limit\u003d2\u0026marker\u003d{last_item_of_current_page}\""},{"line_number":197,"context_line":"            }"}],"source_content_type":"text/x-rst","patch_set":15,"id":"9a8ffd7b_4d643a21","line":194,"in_reply_to":"9a8ffd7b_ba76913c","updated":"2015-11-26 09:07:17.000000000","message":"Cinder is using \"xxx_links\": [{\"rel\": \"next\", \"href\": \"xxxx\"}], pretty much same as nova.","commit_id":"c1a05289c5b4327e5321d5c6882fe677df2f0d2d"},{"author":{"_account_id":782,"name":"John Garbutt","email":"john@johngarbutt.com","username":"johngarbutt"},"change_message_id":"5d361efdd205446007d164a3e180affa6bc52c55","unresolved":false,"context_lines":[{"line_number":207,"context_line":"The following points are recommended:"},{"line_number":208,"context_line":""},{"line_number":209,"context_line":"- The next page link \u0027next\u0027 will only appear in the \u0027_links\u0027 dict, when there"},{"line_number":210,"context_line":"  are more records than shown in the current page."},{"line_number":211,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":212,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":213,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."}],"source_content_type":"text/x-rst","patch_set":15,"id":"9a8ffd7b_e0da3978","line":210,"updated":"2015-11-24 17:46:04.000000000","message":"Nit: I wonder if we should say that _link is always present?","commit_id":"c1a05289c5b4327e5321d5c6882fe677df2f0d2d"},{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"e630f1d601610835424ee13d25ea801018194dff","unresolved":false,"context_lines":[{"line_number":155,"context_line":"and \u0027sort_dir\u0027 query string parameters, see [1]. As these projects adopt these"},{"line_number":156,"context_line":"guidelines, they should deprecate the older parameters appropriately."},{"line_number":157,"context_line":""},{"line_number":158,"context_line":"Pagination"},{"line_number":159,"context_line":"----------"},{"line_number":160,"context_line":""},{"line_number":161,"context_line":"Pagination supports returning a maximum number of items in a single HTTP"}],"source_content_type":"text/x-rst","patch_set":16,"id":"da6ed579_a72ee6f8","line":158,"updated":"2016-01-14 20:42:00.000000000","message":"It should be possible to determine the number of available records so we can provide this to a user interface. \"Showing records X to Y of Z\". Some API\u0027s do this by returning a custom header (X-Total), but it may be that an additional property in the body response is sufficient.","commit_id":"f22e7e7003372f0365d0b979f40af78b0dfafe5d"},{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"e630f1d601610835424ee13d25ea801018194dff","unresolved":false,"context_lines":[{"line_number":166,"context_line":"         positive integer."},{"line_number":167,"context_line":"- marker: the ID of a reference item."},{"line_number":168,"context_line":""},{"line_number":169,"context_line":"The next page link should be added to the \u0027links\u0027 list on the response for"},{"line_number":170,"context_line":"list operations, and \u0027links\u0027 follows the JSON Hyper-Schema, see [2]_."},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"An example of a request:"}],"source_content_type":"text/x-rst","patch_set":16,"id":"da6ed579_e7e61e43","line":169,"range":{"start_line":169,"start_character":4,"end_line":169,"end_character":18},"updated":"2016-01-14 20:42:00.000000000","message":"A previous page link must be available, to support user interfaces that present list data to a human via a web interface.","commit_id":"f22e7e7003372f0365d0b979f40af78b0dfafe5d"},{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"faf6d6ff14c210ac28d684257a8ad006f5264268","unresolved":false,"context_lines":[{"line_number":211,"context_line":"        ]"},{"line_number":212,"context_line":"    }"},{"line_number":213,"context_line":""},{"line_number":214,"context_line":"Note that, all the four parameters are optional. By default, if \u0027marker\u0027 is not"},{"line_number":215,"context_line":"set, the response will be the first page. And if \u0027limit\u0027 is not set, the number"},{"line_number":216,"context_line":"of items returned will be the maximum allowed, and this is generally controlled"},{"line_number":217,"context_line":"via config options in each project. Sorting and filtering parameters could also"}],"source_content_type":"text/x-rst","patch_set":18,"id":"7a5de9d1_d002716f","line":214,"range":{"start_line":214,"start_character":9,"end_line":214,"end_character":10},"updated":"2016-01-27 13:09:03.000000000","message":"Remove comma, these are not two separate clauses.","commit_id":"f25863734956c7fa7ca8bf1df02847335d6664ff"},{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"faf6d6ff14c210ac28d684257a8ad006f5264268","unresolved":false,"context_lines":[{"line_number":220,"context_line":"The following points are recommended:"},{"line_number":221,"context_line":""},{"line_number":222,"context_line":"- The \u0027links\u0027 list is always present. The next page href will only appear,"},{"line_number":223,"context_line":"  when there are more records than shown in the current page. So as to the"},{"line_number":224,"context_line":"  previous page href."},{"line_number":225,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":226,"context_line":"  deployment, the results will be the maximum limit number of items."}],"source_content_type":"text/x-rst","patch_set":18,"id":"7a5de9d1_b034954a","line":223,"range":{"start_line":223,"start_character":62,"end_line":223,"end_character":74},"updated":"2016-01-27 13:09:03.000000000","message":"\"The same applies to the\"","commit_id":"f25863734956c7fa7ca8bf1df02847335d6664ff"},{"author":{"_account_id":10215,"name":"Peter Stachowski","email":"peter@tesora.com","username":"peterstac"},"change_message_id":"1f4f4d92daa13386e376e5f761ac871a51a9e646","unresolved":false,"context_lines":[{"line_number":170,"context_line":"- offset: The offset of the first item returned. Default is 0."},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"The previous link and the next page link should be added to the \u0027links\u0027 list"},{"line_number":173,"context_line":"on the response forlist operations, and \u0027links\u0027 follows the JSON Hyper-Schema,"},{"line_number":174,"context_line":"see [2]_. \u0027offset\u0027 and \u0027total\u0027 are also returned to support the offset-based"},{"line_number":175,"context_line":"pagination."},{"line_number":176,"context_line":""}],"source_content_type":"text/x-rst","patch_set":19,"id":"7a5de9d1_2fbcb06b","line":173,"range":{"start_line":173,"start_character":16,"end_line":173,"end_character":23},"updated":"2016-01-27 18:09:07.000000000","message":"Missing a space here","commit_id":"613bbea0a8a2742774abd55fff5d3f7b0b3c52cc"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"dba41768a07bc646b83206640420b0b696c4e8cd","unresolved":false,"context_lines":[{"line_number":219,"context_line":""},{"line_number":220,"context_line":"The following points are recommended:"},{"line_number":221,"context_line":""},{"line_number":222,"context_line":"- The \u0027links\u0027 list is always present. The next page href will only appear, when"},{"line_number":223,"context_line":"  there are more records than shown in the current page. The same applies to"},{"line_number":224,"context_line":"  the previous page href."},{"line_number":225,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":226,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":227,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."}],"source_content_type":"text/x-rst","patch_set":19,"id":"7a5de9d1_808d717d","line":224,"range":{"start_line":222,"start_character":38,"end_line":224,"end_character":25},"updated":"2016-01-27 18:39:54.000000000","message":"I would like some language stating that in many cases, a \u0027previous\u0027 link has no meaning, and should be omitted. I understand the GUI argument for including it, but also feel that in the vast majority of non-GUI cases, \u0027previous\u0027 has no definite meaning.","commit_id":"613bbea0a8a2742774abd55fff5d3f7b0b3c52cc"},{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"b1fbf455225c9ea54ab094abaed7d16b8bf2f44b","unresolved":false,"context_lines":[{"line_number":219,"context_line":""},{"line_number":220,"context_line":"The following points are recommended:"},{"line_number":221,"context_line":""},{"line_number":222,"context_line":"- The \u0027links\u0027 list is always present. The next page href will only appear, when"},{"line_number":223,"context_line":"  there are more records than shown in the current page. The same applies to"},{"line_number":224,"context_line":"  the previous page href."},{"line_number":225,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":226,"context_line":"  deployment, the results will be the maximum limit number of items."},{"line_number":227,"context_line":"- If the specified \u0027marker\u0027 doesn\u0027t exist, the response will be 404 Not Found."}],"source_content_type":"text/x-rst","patch_set":19,"id":"3a57f1b5_444ff86a","line":224,"range":{"start_line":222,"start_character":38,"end_line":224,"end_character":25},"in_reply_to":"7a5de9d1_808d717d","updated":"2016-02-12 15:01:05.000000000","message":"You\u0027re making an assumption about usage here: \"Oh well most people won\u0027t be using the GUI use case\". Using assumptions about user behavior, especially ones as broadly generalized as this one, is not a valid argument, especially since you haven\u0027t provided any concrete evidence of desired user behavior.","commit_id":"613bbea0a8a2742774abd55fff5d3f7b0b3c52cc"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"9eef5af534f1088fc3125ad185b5a6568dcdb99a","unresolved":false,"context_lines":[{"line_number":158,"context_line":"Pagination"},{"line_number":159,"context_line":"----------"},{"line_number":160,"context_line":""},{"line_number":161,"context_line":"Pagination supports returning a maximum number of items in a single HTTP"},{"line_number":162,"context_line":"response. To navigate the collection, the parameters \u0027limit\u0027, \u0027marker\u0027,"},{"line_number":163,"context_line":"\u0027page_reverse\u0027 and offset can be set in the URI."},{"line_number":164,"context_line":""}],"source_content_type":"text/x-rst","patch_set":20,"id":"7a5de9d1_ef4acaab","line":161,"range":{"start_line":161,"start_character":32,"end_line":161,"end_character":39},"updated":"2016-01-29 19:32:05.000000000","message":"suggest replacing maximum with limited","commit_id":"1a65ec2e1891085cb5d3ad1025170d51a676b714"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"9eef5af534f1088fc3125ad185b5a6568dcdb99a","unresolved":false,"context_lines":[{"line_number":166,"context_line":"         positive integer."},{"line_number":167,"context_line":"- marker: the ID of a reference item."},{"line_number":168,"context_line":"- page_reverse: set the direction of pagination, which can only be \u0027True\u0027 or"},{"line_number":169,"context_line":"                \u0027False\u0027. Default is False."},{"line_number":170,"context_line":"- offset: The offset of the first item returned. Default is 0."},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"The previous link and the next page link should be added to the \u0027links\u0027 list"}],"source_content_type":"text/x-rst","patch_set":20,"id":"7a5de9d1_0bfb6c48","line":169,"updated":"2016-01-29 19:32:05.000000000","message":"We should probably prescribe specific behaviors when the page_reverse parameter is used. Specifically there could be misinterpretation around an implied reverse of sort order when this is true.\n\nSecondly, didn\u0027t we at some point establish some guidance on the handling of boolean interpolation, or did we drop it? I really don\u0027t like the expectation of a mixed-case string and I\u0027m not finding it mentioned among the current guidelines.","commit_id":"1a65ec2e1891085cb5d3ad1025170d51a676b714"},{"author":{"_account_id":1112,"name":"Everett Toews","email":"everett.toews@rackspace.com","username":"everett-toews"},"change_message_id":"91dae1452f21385a84277aa62707ee9ccb7f532d","unresolved":false,"context_lines":[{"line_number":166,"context_line":"         positive integer."},{"line_number":167,"context_line":"- marker: the ID of a reference item."},{"line_number":168,"context_line":"- page_reverse: set the direction of pagination, which can only be \u0027True\u0027 or"},{"line_number":169,"context_line":"                \u0027False\u0027. Default is False."},{"line_number":170,"context_line":"- offset: The offset of the first item returned. Default is 0."},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"The previous link and the next page link should be added to the \u0027links\u0027 list"}],"source_content_type":"text/x-rst","patch_set":20,"id":"7a5de9d1_8ee52add","line":169,"in_reply_to":"7a5de9d1_0bfb6c48","updated":"2016-01-29 19:42:55.000000000","message":"I think you\u0027re thinking of this https://review.openstack.org/#/c/162716/\n\nMy recommendation is to abandon that ^ patch set and that instead a guideline is created in naming.rst that specifies the one value that must be used to indicate true/false. That guideline would also update this guideline to remove\n\n    Any value that equates to True indicates that the count should be returned;\tconversely, any value that equates to False indicates that the count should not be returned.\n\nand reference the naming convention for boolean string values. Let me know what you think over there.","commit_id":"1a65ec2e1891085cb5d3ad1025170d51a676b714"},{"author":{"_account_id":12807,"name":"Steve Lewis (stevelle)","email":"stevelle@gmail.com","username":"stevelle"},"change_message_id":"29c20f81f01ffcb0c080cc68931d6609637719b9","unresolved":false,"context_lines":[{"line_number":166,"context_line":"         positive integer."},{"line_number":167,"context_line":"- marker: the ID of a reference item."},{"line_number":168,"context_line":"- page_reverse: set the direction of pagination, which can only be \u0027True\u0027 or"},{"line_number":169,"context_line":"                \u0027False\u0027. Default is False."},{"line_number":170,"context_line":"- offset: The offset of the first item returned. Default is 0."},{"line_number":171,"context_line":""},{"line_number":172,"context_line":"The previous link and the next page link should be added to the \u0027links\u0027 list"}],"source_content_type":"text/x-rst","patch_set":20,"id":"7a5de9d1_3a4eb03b","line":169,"in_reply_to":"7a5de9d1_8ee52add","updated":"2016-01-29 21:15:43.000000000","message":"That sound about right, for my second point, and I believe that at this point the abandonment sounds right on that review.\n\nI am mildly concerned about interim solutions going with \u0027True\u0027 as the expected value though I have not done a survey of API changes in progress.","commit_id":"1a65ec2e1891085cb5d3ad1025170d51a676b714"},{"author":{"_account_id":12175,"name":"Eli Qiao","email":"qiaoliyong@gmail.com","username":"Eli"},"change_message_id":"c22e2086daa4ef3aa4cfe585fece8f10f75a081c","unresolved":false,"context_lines":[{"line_number":162,"context_line":"response. To navigate the collection, the parameters \u0027limit\u0027, \u0027marker\u0027,"},{"line_number":163,"context_line":"\u0027page_reverse\u0027 and offset can be set in the URI."},{"line_number":164,"context_line":""},{"line_number":165,"context_line":"- limit: determine the number of items on the response, which should be a"},{"line_number":166,"context_line":"         positive integer."},{"line_number":167,"context_line":"- marker: the ID of a reference item."},{"line_number":168,"context_line":"- page_reverse: set the direction of pagination, which is a boolean string."},{"line_number":169,"context_line":"                Default is False, and it indicates that the sort order isn\u0027t"}],"source_content_type":"text/x-rst","patch_set":21,"id":"ba0121b8_309b0374","line":166,"range":{"start_line":165,"start_character":0,"end_line":166,"end_character":26},"updated":"2016-03-31 03:32:27.000000000","message":"in python-novaclient, if passing limit\u003d-1, which mean infinity, I think this is acceptable in CLI, can you mention -1 value here?(although API don\u0027t support -1)\n\nEli.","commit_id":"022a1cf9738534b5593684bde49440127becde9c"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"fb69c79359bef45c444f52b429e90aecc7ddf375","unresolved":false,"context_lines":[{"line_number":167,"context_line":"- marker: the ID of a reference item."},{"line_number":168,"context_line":"- page_reverse: set the direction of pagination, which is a boolean string."},{"line_number":169,"context_line":"                Default is False, and it indicates that the sort order isn\u0027t"},{"line_number":170,"context_line":"                reversed."},{"line_number":171,"context_line":"- offset: The offset of the first item returned. Default is 0."},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"The previous link and the next page link should be added to the \u0027links\u0027 list"}],"source_content_type":"text/x-rst","patch_set":21,"id":"3a57f1b5_d4af1328","line":170,"updated":"2016-02-12 15:55:04.000000000","message":"This description is unclear. The implication is that the contents of the page will be sorted in reverse order, not that marker indicates the end+1 of the page that should be displayed, rather than start-1.\n\nI\u0027m not certain how this should be clarified but neither the name nor the descriptive text make it clear enough.","commit_id":"022a1cf9738534b5593684bde49440127becde9c"},{"author":{"_account_id":6524,"name":"Henry Gessau","email":"HenryG@gessau.net","username":"gessau"},"change_message_id":"59919542124c94cc5370ce819b42ca4cf0af8a2f","unresolved":false,"context_lines":[{"line_number":167,"context_line":"- marker: the ID of a reference item."},{"line_number":168,"context_line":"- page_reverse: set the direction of pagination, which is a boolean string."},{"line_number":169,"context_line":"                Default is False, and it indicates that the sort order isn\u0027t"},{"line_number":170,"context_line":"                reversed."},{"line_number":171,"context_line":"- offset: The offset of the first item returned. Default is 0."},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"The previous link and the next page link should be added to the \u0027links\u0027 list"}],"source_content_type":"text/x-rst","patch_set":21,"id":"9abb7d3a_870b2c2b","line":170,"in_reply_to":"3a57f1b5_d4af1328","updated":"2016-06-02 13:07:59.000000000","message":"The way I understand it, it is the direction the user is scrolling (up or down). If my understanding is correct then \"sort order\" is misleading here and that term should probably be avoided in this context.","commit_id":"022a1cf9738534b5593684bde49440127becde9c"},{"author":{"_account_id":2750,"name":"Sean Dague","email":"sean@dague.net","username":"sdague"},"change_message_id":"52180bbc999442f2762a889a5f0f97215ce7d141","unresolved":false,"context_lines":[{"line_number":167,"context_line":"- marker: the ID of a reference item."},{"line_number":168,"context_line":"- page_reverse: set the direction of pagination, which is a boolean string."},{"line_number":169,"context_line":"                Default is False, and it indicates that the sort order isn\u0027t"},{"line_number":170,"context_line":"                reversed."},{"line_number":171,"context_line":"- offset: The offset of the first item returned. Default is 0."},{"line_number":172,"context_line":""},{"line_number":173,"context_line":"The previous link and the next page link should be added to the \u0027links\u0027 list"}],"source_content_type":"text/x-rst","patch_set":21,"id":"9abb7d3a_1ac49d3e","line":170,"in_reply_to":"9abb7d3a_870b2c2b","updated":"2016-06-02 17:36:54.000000000","message":"I really thought we had properly settled on limit/marker for pagination. I\u0027m not really sure where offset jumped back in here from. \n\nPagination really should be about going through a whole list in chunks, I don\u0027t like the offset or page_reverse adds.","commit_id":"022a1cf9738534b5593684bde49440127becde9c"},{"author":{"_account_id":9717,"name":"Michael Krotscheck","email":"krotscheck@gmail.com","username":"krotscheck"},"change_message_id":"76c5ac78c67923098d259ef3a682b542b464e127","unresolved":false,"context_lines":[{"line_number":220,"context_line":""},{"line_number":221,"context_line":"The following points are recommended:"},{"line_number":222,"context_line":""},{"line_number":223,"context_line":"- The \u0027links\u0027 list is always present. For each individual API, the previous"},{"line_number":224,"context_line":"  page link is optional according to the use case. For a request, The next link"},{"line_number":225,"context_line":"  will only appear, when there are more records than shown in the current page."},{"line_number":226,"context_line":"  The same applies to the previous page link."},{"line_number":227,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":228,"context_line":"  deployment, the results will be the maximum limit number of items."}],"source_content_type":"text/x-rst","patch_set":21,"id":"3a57f1b5_84b73039","line":225,"range":{"start_line":223,"start_character":0,"end_line":225,"end_character":79},"updated":"2016-02-12 15:01:12.000000000","message":"Remove the language that indicates that the previous page link is optional. If you include it, developers will use the \u0027oh that\u0027s just optional\u0027 excuse to skip implementation altogether, or to push it onto the GUI developers as a \"Well if you want it, do it yourself\" argument.","commit_id":"022a1cf9738534b5593684bde49440127becde9c"},{"author":{"_account_id":261,"name":"Salvatore Orlando","email":"salv.orlando@gmail.com","username":"salvatore-orlando"},"change_message_id":"f03b6548baa0b898fa8b30da27ba3154db943059","unresolved":false,"context_lines":[{"line_number":222,"context_line":""},{"line_number":223,"context_line":"- The \u0027links\u0027 list is always present. For each individual API, the previous"},{"line_number":224,"context_line":"  page link is optional according to the use case. For a request, The next link"},{"line_number":225,"context_line":"  will only appear, when there are more records than shown in the current page."},{"line_number":226,"context_line":"  The same applies to the previous page link."},{"line_number":227,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":228,"context_line":"  deployment, the results will be the maximum limit number of items."}],"source_content_type":"text/x-rst","patch_set":21,"id":"bae84128_86089129","line":225,"in_reply_to":"3a57f1b5_34330716","updated":"2016-02-24 09:58:51.000000000","message":"It should be removed because this is a guideline, so there are no mandatory or optional things to implement, but just a description about how should be done in the ideal case.\n\nAnd then I\u0027m sure API devs will always find a way to make the life of GUI devs extraordinary difficult.\n\n...unless the author has a meaningful use case where a link to the previous page makes no sense.","commit_id":"022a1cf9738534b5593684bde49440127becde9c"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"fb69c79359bef45c444f52b429e90aecc7ddf375","unresolved":false,"context_lines":[{"line_number":222,"context_line":""},{"line_number":223,"context_line":"- The \u0027links\u0027 list is always present. For each individual API, the previous"},{"line_number":224,"context_line":"  page link is optional according to the use case. For a request, The next link"},{"line_number":225,"context_line":"  will only appear, when there are more records than shown in the current page."},{"line_number":226,"context_line":"  The same applies to the previous page link."},{"line_number":227,"context_line":"- If the client requests a limit beyond the maximum limit configured by the"},{"line_number":228,"context_line":"  deployment, the results will be the maximum limit number of items."}],"source_content_type":"text/x-rst","patch_set":21,"id":"3a57f1b5_34330716","line":225,"in_reply_to":"3a57f1b5_84b73039","updated":"2016-02-12 15:55:04.000000000","message":"Yes","commit_id":"022a1cf9738534b5593684bde49440127becde9c"}]}