)]}'
{"guidelines/api-design.rst":[{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"148fffbe54a8509a6a0380a918cbf4808acd0bc4","unresolved":false,"context_lines":[{"line_number":25,"context_line":"* What things do I have in this system?"},{"line_number":26,"context_line":"* What do I want to get done with this system?"},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"Then, looking at the answers to the second question, identify the nouns"},{"line_number":29,"context_line":"(resources) in those answers and add them to a list of potential resources"},{"line_number":30,"context_line":"that also contains the answers to the first question."},{"line_number":31,"context_line":""},{"line_number":32,"context_line":"With that list of potential resources ask:"},{"line_number":33,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"3f79a3b5_b34f7669","line":30,"range":{"start_line":28,"start_character":0,"end_line":30,"end_character":53},"updated":"2018-08-15 13:33:24.000000000","message":"This paragraph is really awkwardly phrased. It took me three reads to parse what you were saying. How just going with:\n\n*What do I want this system to do?* There will very likely be many things that you come up with. Create a list of those things, and then identify the nouns in them. Those nouns are the resources for your system.","commit_id":"7189d8bdddb1c4f394054050f6a50cb2bac85339"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"0148c95b6b0313eb507e311f3a17f21f82e0c311","unresolved":false,"context_lines":[{"line_number":25,"context_line":"* What things do I have in this system?"},{"line_number":26,"context_line":"* What do I want to get done with this system?"},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"Then, looking at the answers to the second question, identify the nouns"},{"line_number":29,"context_line":"(resources) in those answers and add them to a list of potential resources"},{"line_number":30,"context_line":"that also contains the answers to the first question."},{"line_number":31,"context_line":""},{"line_number":32,"context_line":"With that list of potential resources ask:"},{"line_number":33,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"3f79a3b5_df51d337","line":30,"range":{"start_line":28,"start_character":0,"end_line":30,"end_character":53},"in_reply_to":"3f79a3b5_13fc2ab3","updated":"2018-08-15 15:44:00.000000000","message":"In my experience, there are \"things\" in a system that end up not being relevant to the operation of the system. Defining what a system needs to do is always the first step, IMO.","commit_id":"7189d8bdddb1c4f394054050f6a50cb2bac85339"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"7536a2a7774388ef078f3152dd01430767f22009","unresolved":false,"context_lines":[{"line_number":25,"context_line":"* What things do I have in this system?"},{"line_number":26,"context_line":"* What do I want to get done with this system?"},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"Then, looking at the answers to the second question, identify the nouns"},{"line_number":29,"context_line":"(resources) in those answers and add them to a list of potential resources"},{"line_number":30,"context_line":"that also contains the answers to the first question."},{"line_number":31,"context_line":""},{"line_number":32,"context_line":"With that list of potential resources ask:"},{"line_number":33,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"3f79a3b5_37fcee70","line":30,"range":{"start_line":28,"start_character":0,"end_line":30,"end_character":53},"in_reply_to":"3f79a3b5_aa585730","updated":"2018-08-23 13:37:43.000000000","message":"maybe i\u0027m just weird, but it actually made sense to me. then again, most of my stuff needs heavy editing anyways lol.\n\nto the larger point, i like the idea of identifying the resources and instructing folks to start decomposing their api like that.","commit_id":"7189d8bdddb1c4f394054050f6a50cb2bac85339"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"58d78a1d380c41d6c4f7e5490b7db6ca2e9390e2","unresolved":false,"context_lines":[{"line_number":25,"context_line":"* What things do I have in this system?"},{"line_number":26,"context_line":"* What do I want to get done with this system?"},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"Then, looking at the answers to the second question, identify the nouns"},{"line_number":29,"context_line":"(resources) in those answers and add them to a list of potential resources"},{"line_number":30,"context_line":"that also contains the answers to the first question."},{"line_number":31,"context_line":""},{"line_number":32,"context_line":"With that list of potential resources ask:"},{"line_number":33,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"3f79a3b5_13fc2ab3","line":30,"range":{"start_line":28,"start_character":0,"end_line":30,"end_character":53},"in_reply_to":"3f79a3b5_b34f7669","updated":"2018-08-15 13:40:50.000000000","message":"Yeah, it is very awkward, very first draft.\n\nHowever, the critical piece of advice, probably not captured well here is that you need both questions. There are already the things that you know the system has  (compute has servers). Those are important.\n\nEqually important are the things you only think of after you\u0027ve thought about what you want to do (perhaps, I want users to be able to create servers that have different flavors).\n\nIn my experience if you think about \"What do I want this system to do?\" without the breakdown described above you get an incomplete design.","commit_id":"7189d8bdddb1c4f394054050f6a50cb2bac85339"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"b133bf07ed6eea1ac8166c261a64a90a5fa1b404","unresolved":false,"context_lines":[{"line_number":25,"context_line":"* What things do I have in this system?"},{"line_number":26,"context_line":"* What do I want to get done with this system?"},{"line_number":27,"context_line":""},{"line_number":28,"context_line":"Then, looking at the answers to the second question, identify the nouns"},{"line_number":29,"context_line":"(resources) in those answers and add them to a list of potential resources"},{"line_number":30,"context_line":"that also contains the answers to the first question."},{"line_number":31,"context_line":""},{"line_number":32,"context_line":"With that list of potential resources ask:"},{"line_number":33,"context_line":""}],"source_content_type":"text/x-rst","patch_set":2,"id":"3f79a3b5_aa585730","line":30,"range":{"start_line":28,"start_character":0,"end_line":30,"end_character":53},"in_reply_to":"3f79a3b5_df51d337","updated":"2018-08-15 15:49:17.000000000","message":"Ah, I see the problem here. I\u0027m starting from the standpoint of \"we have a system (already) in mind and we want to put an API on it\"\n\nNot, we are defining a system.\n\nNot sure how/if we want to resolve that.","commit_id":"7189d8bdddb1c4f394054050f6a50cb2bac85339"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"148fffbe54a8509a6a0380a918cbf4808acd0bc4","unresolved":false,"context_lines":[{"line_number":34,"context_line":"* What *can* I do with these things?"},{"line_number":35,"context_line":"* What *must* I do with these things?"},{"line_number":36,"context_line":"* What must I *prevent* being done to these things?"},{"line_number":37,"context_line":"* How are these things interrelated?"},{"line_number":38,"context_line":"* Now that I\u0027ve looked more closely, are any of these things the same thing?"},{"line_number":39,"context_line":""},{"line_number":40,"context_line":"After doing that analysis it then becomes possible to make arrangements of the"},{"line_number":41,"context_line":"resources and the state changes being considered and see if there is a"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3f79a3b5_13b2ea49","line":38,"range":{"start_line":37,"start_character":0,"end_line":38,"end_character":76},"updated":"2018-08-15 13:33:24.000000000","message":"These two points should probably be moved above the three action questions. IOW, first come up with a list of resources, and then think about any relationships between them to possibly identify the things that you listed as separate that are actually versions of the same thing.","commit_id":"7189d8bdddb1c4f394054050f6a50cb2bac85339"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"58d78a1d380c41d6c4f7e5490b7db6ca2e9390e2","unresolved":false,"context_lines":[{"line_number":34,"context_line":"* What *can* I do with these things?"},{"line_number":35,"context_line":"* What *must* I do with these things?"},{"line_number":36,"context_line":"* What must I *prevent* being done to these things?"},{"line_number":37,"context_line":"* How are these things interrelated?"},{"line_number":38,"context_line":"* Now that I\u0027ve looked more closely, are any of these things the same thing?"},{"line_number":39,"context_line":""},{"line_number":40,"context_line":"After doing that analysis it then becomes possible to make arrangements of the"},{"line_number":41,"context_line":"resources and the state changes being considered and see if there is a"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3f79a3b5_73b47ef2","line":38,"range":{"start_line":37,"start_character":0,"end_line":38,"end_character":76},"in_reply_to":"3f79a3b5_13b2ea49","updated":"2018-08-15 13:40:50.000000000","message":"Perhaps. Again, in my experience, the relationships and sameness-es are more clear after I think about the first three things.\n\nI agree that it is somewhat counter-intuitive, but that\u0027s kind of the point: this is a methodology to break natural patterns.","commit_id":"7189d8bdddb1c4f394054050f6a50cb2bac85339"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"7536a2a7774388ef078f3152dd01430767f22009","unresolved":false,"context_lines":[{"line_number":34,"context_line":"* What *can* I do with these things?"},{"line_number":35,"context_line":"* What *must* I do with these things?"},{"line_number":36,"context_line":"* What must I *prevent* being done to these things?"},{"line_number":37,"context_line":"* How are these things interrelated?"},{"line_number":38,"context_line":"* Now that I\u0027ve looked more closely, are any of these things the same thing?"},{"line_number":39,"context_line":""},{"line_number":40,"context_line":"After doing that analysis it then becomes possible to make arrangements of the"},{"line_number":41,"context_line":"resources and the state changes being considered and see if there is a"}],"source_content_type":"text/x-rst","patch_set":2,"id":"3f79a3b5_d741faa7","line":38,"range":{"start_line":37,"start_character":0,"end_line":38,"end_character":76},"in_reply_to":"3f79a3b5_73b47ef2","updated":"2018-08-23 13:37:43.000000000","message":"i vote for leaving them at the bottom, i can dig the idea of building these queries up in a way that promotes a certain style of thought about the problem.","commit_id":"7189d8bdddb1c4f394054050f6a50cb2bac85339"},{"author":{"_account_id":1063,"name":"Ed Leafe","email":"ed@leafe.com","username":"ed-leafe"},"change_message_id":"148fffbe54a8509a6a0380a918cbf4808acd0bc4","unresolved":false,"context_lines":[{"line_number":39,"context_line":""},{"line_number":40,"context_line":"After doing that analysis it then becomes possible to make arrangements of the"},{"line_number":41,"context_line":"resources and the state changes being considered and see if there is a"},{"line_number":42,"context_line":"comprehensible resource-oriented approach to the API."}],"source_content_type":"text/x-rst","patch_set":2,"id":"3f79a3b5_339a86b8","line":42,"updated":"2018-08-15 13:33:24.000000000","message":"Probably needs an example. I can see about coming up with one that we can all enhance.","commit_id":"7189d8bdddb1c4f394054050f6a50cb2bac85339"},{"author":{"_account_id":11564,"name":"Chris Dent","email":"cdent@anticdent.org","username":"chdent"},"change_message_id":"58d78a1d380c41d6c4f7e5490b7db6ca2e9390e2","unresolved":false,"context_lines":[{"line_number":39,"context_line":""},{"line_number":40,"context_line":"After doing that analysis it then becomes possible to make arrangements of the"},{"line_number":41,"context_line":"resources and the state changes being considered and see if there is a"},{"line_number":42,"context_line":"comprehensible resource-oriented approach to the API."}],"source_content_type":"text/x-rst","patch_set":2,"id":"3f79a3b5_93acba9f","line":42,"in_reply_to":"3f79a3b5_339a86b8","updated":"2018-08-15 13:40:50.000000000","message":"Yeah, I didn\u0027t want to go down that route, at least not yet. If you\u0027ve got some ideas, that\u0027s cool, but I was going for a very basic but abstract hint.","commit_id":"7189d8bdddb1c4f394054050f6a50cb2bac85339"},{"author":{"_account_id":10670,"name":"Michael McCune","email":"elmiko@redhat.com","username":"mimccune"},"change_message_id":"7536a2a7774388ef078f3152dd01430767f22009","unresolved":false,"context_lines":[{"line_number":39,"context_line":""},{"line_number":40,"context_line":"After doing that analysis it then becomes possible to make arrangements of the"},{"line_number":41,"context_line":"resources and the state changes being considered and see if there is a"},{"line_number":42,"context_line":"comprehensible resource-oriented approach to the API."}],"source_content_type":"text/x-rst","patch_set":2,"id":"3f79a3b5_7714a6a0","line":42,"in_reply_to":"3f79a3b5_93acba9f","updated":"2018-08-23 13:37:43.000000000","message":"++ an example would be tremendous, but i can acknowledge the difficulty in arriving at that example.","commit_id":"7189d8bdddb1c4f394054050f6a50cb2bac85339"},{"author":{"_account_id":11604,"name":"sean mooney","email":"smooney@redhat.com","username":"sean-k-mooney"},"change_message_id":"151d14b05bd4e5196160c9a9542083f3cf78ca0c","unresolved":false,"context_lines":[{"line_number":4,"context_line":"This section of the guidelines provides advice on how to effectively design an"},{"line_number":5,"context_line":"API."},{"line_number":6,"context_line":""},{"line_number":7,"context_line":"Generally most OpenStack APIs call themselves \"REST\" APIs and align themselves"},{"line_number":8,"context_line":"with the concept of resources. That is, the URLs in the APIs represent nouns or"},{"line_number":9,"context_line":"things in the system on which the client wants to change some state. They want"},{"line_number":10,"context_line":"to cause it to exist, or stop existing, or change in some way. Designing APIs"}],"source_content_type":"text/x-rst","patch_set":3,"id":"3f79a3b5_93517668","line":7,"range":{"start_line":7,"start_character":46,"end_line":7,"end_character":56},"updated":"2018-11-21 14:08:30.000000000","message":"openstack service apis are what i would generally consider \n\npargmatic rest apis\n\nthey are not pure rest apis but when there is a restful way to do so we strongly support it while acknowledging that is not always the right choice i think this into conveys that sentiment more or less.","commit_id":"fda63b924237cb6361860d77f80898f152091ced"},{"author":{"_account_id":11604,"name":"sean mooney","email":"smooney@redhat.com","username":"sean-k-mooney"},"change_message_id":"151d14b05bd4e5196160c9a9542083f3cf78ca0c","unresolved":false,"context_lines":[{"line_number":33,"context_line":""},{"line_number":34,"context_line":"* What *can* I do with these things?"},{"line_number":35,"context_line":"* What *must* I do with these things?"},{"line_number":36,"context_line":"* What must I *prevent* being done to these things?"},{"line_number":37,"context_line":"* How are these things interrelated?"},{"line_number":38,"context_line":"* Now that I\u0027ve looked more closely, are any of these things the same thing?"},{"line_number":39,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"3f79a3b5_731e1abd","line":36,"range":{"start_line":36,"start_character":3,"end_line":36,"end_character":51},"updated":"2018-11-21 14:08:30.000000000","message":"this is important and sometimes overlooked.","commit_id":"fda63b924237cb6361860d77f80898f152091ced"}]}