Merge pull request #86 from AdaGold/ks_update_response_structure

Update Create & Get One endpoints response structures

Author: kelsey-steven-ada

ada-project-docs/wave_01.md

@@ -55,17 +55,21 @@ We might also consider creating a route helper method that can:
 
 ## CRUD for Tasks
 
-### Tips
+Use the tests in `tests/test_wave_01.py` to guide your implementation.
 
-- Pay attention to the exact shape of the expected JSON. Double-check nested data structures and the names of the keys for any misspellings.
-  - That said, remember that dictionaries do not have an implied order. This is still true in JSON with objects. When you make Postman requests, the order of the key/value pairings within the response JSON object does not need to match the order specified in this document. (The term "object" in JSON is analogous to "dictionary" in Python.)
-  - Notice that the details for a Task in the response is shared across all the endpoints that return Task details. Rather than repeating the same literal `dict` structure in each response, we should create a helper method that returns the `dict` structure for a Task, and use it in each relevant endpoint. This will ensure that all our responses are consistent.
-- Use the tests in `tests/test_wave_01.py` to guide your implementation.
 - You may feel that there are missing tests and missing edge cases considered in this wave. This is intentional.
   - You have fulfilled wave 1 requirements if all of the wave 1 tests pass.
   - You are free to add additional features, as long as the wave 1 tests still pass. However, we recommend that you consider the future waves, first.
 - Some tests use a fixture named `one_task` that is defined in `tests/conftest.py`. This fixture saves a specific task to the test database.
 
+### CRUD Tips
+
+- Pay attention to the exact shape of the expected JSON. Double-check nested data structures and the names of the keys for any misspellings.
+  - That said, remember that dictionaries do not have an implied order. This is still true in JSON with objects. When you make Postman requests, the order of the key/value pairings within the response JSON object does not need to match the order specified in this document. (The term "object" in JSON is analogous to "dictionary" in Python.)
+- Notice that the details for a Task in the response is shared across all the endpoints that return Task details. Rather than repeating the same literal `dict` structure in each response, we should create a helper method that returns the `dict` structure for a Task, and use it in each relevant endpoint. This will ensure that all our responses are consistent.
+- We should remember that retrieving a model by its ID is a common operation. We should consider creating a route helper method that can retrieve a model by its ID, and use it in all applicable routes. 
+    - This method could start out only working for Task models. But, knowing that we'll be working with Goal models later on, it might be worth generalizing this method to work with any model.
+
 ### CLI
 
 In addition to testing your code with pytest and postman, you can play test your code with the CLI (Command Line Interface) by running `python3 cli/main.py`. 
@@ -94,21 +98,17 @@ and get this response:
 
 ```json
 {
-  "task": {
-    "id": 1,
-    "title": "A Brand New Task",
-    "description": "Test Description",
-    "is_complete": false
-  }
+  "id": 1,
+  "title": "A Brand New Task",
+  "description": "Test Description",
+  "is_complete": false
 }
 ```
 
 so that I know I successfully created a Task that is saved in the database.
 
 Remember that the knowledge of how to initialize a new model instance from the request dictionary is often left to the model itself, as it allows the model to control which fields are required and how they are initialized. We could add a class method to the Task model that initializes a new instance from a dictionary, and use this method in the route. If all of our models have this method, we could create a route helper method that initializes a new model instance from a dictionary, and use it in this route and any other route that creates a new model instance.
 
-Further, notice that the data nested under the `"task"` key is a dictionary representation of the task that was created. Creating a model helper method to return this dictionary, which we can then use to help build this route response, will improve the consistency of our endpoints.
-
 #### Get Tasks: Getting Saved Tasks
 
 As a client, I want to be able to make a `GET` request to `/tasks` when there is at least one saved task and get this response:
@@ -132,8 +132,6 @@ As a client, I want to be able to make a `GET` request to `/tasks` when there is
 ]
 ```
 
-Notice that each data item in the list is a dictionary representation of a task. Creating a model helper method to return this dictionary, which we can then use to help build this route response, will improve the consistency of our endpoints.
-
 #### Get Tasks: No Saved Tasks
 
 As a client, I want to be able to make a `GET` request to `/tasks` when there are zero saved tasks and get this response:
@@ -152,18 +150,13 @@ As a client, I want to be able to make a `GET` request to `/tasks/1` when there
 
 ```json
 {
-  "task": {
-    "id": 1,
-    "title": "Example Task Title 1",
-    "description": "Example Task Description 1",
-    "is_complete": false
-  }
+  "id": 1,
+  "title": "Example Task Title 1",
+  "description": "Example Task Description 1",
+  "is_complete": false
 }
 ```
 
-Notice that the data nested under the `"task"` key is a dictionary representation of the task that was retrieved. Creating a model helper method to return this dictionary, which we can then use to help build this route response, will improve the consistency of our endpoints.
-
-Further, we should remember that retrieving a model by its ID is a common operation. We should consider creating a route helper method that can retrieve a model by its ID, and use it in this route. This method could start out only working for Task models. But knowing that we'll be working with Goal models later on, it might be worth generalizing this method to work with any model.
 
 #### Update Task
 
@@ -184,8 +177,6 @@ The response should have a mimetype of "application/json" to keep our API respon
 
 Note that the update endpoint does update the `completed_at` attribute. This will be updated with custom endpoints implemented in Wave 3.
 
-We should remember that retrieving a model by its ID is a common operation. We should consider creating a route helper method that can retrieve a model by its ID, and use it in this route. This method could start out only working for Task models. But knowing that we'll be working with Goal models later on, it might be worth generalizing this method to work with any model.
-
 #### Delete Task: Deleting a Task
 
 As a client, I want to be able to make a `DELETE` request to `/tasks/1` when there is at least one saved task and get this response:
@@ -194,8 +185,6 @@ As a client, I want to be able to make a `DELETE` request to `/tasks/1` when the
 
 The response should have a mimetype of "application/json" to keep our API response type consistent.
 
-We should remember that retrieving a model by its ID is a common operation. We should consider creating a route helper method that can retrieve a model by its ID, and use it in this route. This method could start out only working for Task models. But knowing that we'll be working with Goal models later on, it might be worth generalizing this method to work with any model.
-
 #### No Matching Task: Get, Update, and Delete
 
 As a client, if I make any of the following requests:

ada-project-docs/wave_02.md

@@ -8,15 +8,16 @@ Our task list API allows users to create tasks and get a list of all tasks. Our
 
 The following are required routes for wave 2. Feel free to implement the routes in any order within this wave.
 
-### Tips
-
-- Pay attention to the exact shape of the expected JSON. Double-check nested data structures and the names of the keys for any misspellings.
-- Use the tests in `tests/test_wave_02.py` to guide your implementation.
+Use the tests in `tests/test_wave_02.py` to guide your implementation.
 - You may feel that there are missing tests and missing edge cases considered in this wave. This is intentional.
   - You have fulfilled wave 2 requirements if all of the wave 2 tests pass.
   - You are free to add additional features, as long as the wave 2 tests still pass. However, we recommend that you consider the future waves, first.
 - Some tests use a fixture named `three_tasks` that is defined in `tests/conftest.py`. This fixture saves three different tasks with three different titles to the test database.
 
+### Tips
+
+- Pay attention to the exact shape of the expected JSON. Double-check nested data structures and the names of the keys for any misspellings.
+
 ### Sorting Tasks: By Title, Ascending
 
 As a client, I want to be able to make a `GET` request to `/tasks?sort=asc` when there is more than one saved task, and get an array of tasks sorted by **title**. The titles should be in _ascending_ order, where a task with the title "A" is sorted before a task with the title "B."

ada-project-docs/wave_03.md

@@ -4,24 +4,28 @@
 
 Our task list API allows users to meaningfully use the task resource. Users want to be able to mark a task as "complete" or "incomplete."
 
-We want to design our API so that it stores a task's `completed_at` date as a datetime value in our database. In this scenario, our API does _not_ give users the `completed_at` date... it only gives the information if `is_complete` is `true` or `false`.
+We want to design our API so that it stores a task's `completed_at` date as a datetime value in our database. In this scenario, our API does _not_ give users the `completed_at` date – it only indicates whether `is_complete` is `true` or `false`.
 
-A task's `is_complete` is `true` when there is a datetime for the task's `completed_at` value. A task's `is_complete` is `false` when there is a `null`/`None` value for the tasks's `completed_at` value.
+A task's `is_complete` is:
+- `true` when there is a datetime for the task's `completed_at` value.
+- `false` when there is a `null`/`None` value for the tasks's `completed_at` value.
 
 ## Requirements
 
 The following are required routes for wave 3. Feel free to implement the routes in any order within this wave.
 
-### Tips
-
-- Use the tests in `tests/test_wave_3.py` to guide your implementation.
+Use the tests in `tests/test_wave_3.py` to guide your implementation.
 - You may feel that there are missing tests and missing edge cases considered in this wave. This is intentional.
   - You have fulfilled wave 3 requirements if all of the wave 3 tests pass.
   - You are free to add additional features, as long as the wave 3 tests still pass. However, we recommend that you consider the future waves, first.
 - A test uses a fixture named `completed_task` that is defined in `tests/conftest.py`. This fixture saves a task with a datetime value in `completed_at` to the test database.
+
+### Tips
+
 - JSON's value of `true` is similar to Python's value of `True`, and `false` is similar to Python's `False`.
 - SQL's value of `null` is similar to Python's value of `None`.
 - Python has a [datetime library](https://docs.python.org/3/library/datetime.html#module-datetime) which we recommend using to represent dates in model attributes.
+- Notice that these routes require that we look up a model by its ID, and then update that model. We should be able to reuse the same route helper methods that we have been using in other Task routes to help build these routes.
 
 ### Mark Complete on an Incomplete Task
 
@@ -44,12 +48,10 @@ After I have made the `PATCH` request, I can submit a `GET` request to `/tasks/1
 
 ```json
 {
-  "task": {
-    "id": 1,
-    "title": "Go on my daily walk 🏞",
-    "description": "Notice something new every day",
-    "is_complete": true
-  }
+  "id": 1,
+  "title": "Go on my daily walk 🏞",
+  "description": "Notice something new every day",
+  "is_complete": true
 }
 ```
 
@@ -74,12 +76,10 @@ After I have made the `PATCH` request, I can submit a `GET` request to `/tasks/1
 
 ```json
 {
-  "task": {
-    "id": 1,
-    "title": "Go on my daily walk 🏞",
-    "description": "Notice something new every day",
-    "is_complete": false
-  }
+  "id": 1,
+  "title": "Go on my daily walk 🏞",
+  "description": "Notice something new every day",
+  "is_complete": false
 }
 ```
 
@@ -104,19 +104,13 @@ After I have made the `PATCH` request, I can submit a `GET` request to `/tasks/1
 
 ```json
 {
-  "task": {
-    "id": 1,
-    "title": "Go on my daily walk 🏞",
-    "description": "Notice something new every day",
-    "is_complete": true
-  }
+  "id": 1,
+  "title": "Go on my daily walk 🏞",
+  "description": "Notice something new every day",
+  "is_complete": true
 }
 ```
 
-Notice the same dictionary structure for the Task data as in our wave 1 routes. We should be able to use any response model helper that we are using in other Task routes to help build this response.
-
-Also notice that fundamentally, this route requires that we look up a model by its ID, and then update that model. We should be able to reuse the same route helper methods that we have been using in other Task routes to help build this route.
-
 ### Mark Incomplete on an Incomplete Task
 
 Given a task that has:
@@ -138,19 +132,13 @@ After I have made the `PATCH` request, I can submit a `GET` request to `/tasks/1
 
 ```json
 {
-  "task": {
-    "id": 1,
-    "title": "Go on my daily walk 🏞",
-    "description": "Notice something new every day",
-    "is_complete": false
-  }
+  "id": 1,
+  "title": "Go on my daily walk 🏞",
+  "description": "Notice something new every day",
+  "is_complete": false
 }
 ```
 
-Notice the same dictionary structure for the Task data as in our wave 1 routes. We should be able to use any response model helper that we are using in other Task routes to help build this response.
-
-Also notice that fundamentally, this route requires that we look up a model by its ID, and then update that model. We should be able to reuse the same route helper methods that we have been using in other Task routes to help build this route.
-
 ## Mark Complete and Mark Incomplete for Missing Tasks
 
 Given that there are no tasks with the ID `1`,

ada-project-docs/wave_04.md

@@ -173,18 +173,13 @@ This feature should not affect other features in other waves, nor should it affe
 
 ### Requirement: Intentional Slackbot Token Location
 
-Our Slackbot token is an API key that needs to be protected.
-
-Include your Slackbot token in your code in an intentional way, following best practices about API keys in code bases.
+Our Slackbot token is an API key that needs to be protected. Include your Slackbot token in your code in an intentional way, following best practices about API keys in code bases.
 
 ### Requirement: Use Python package `requests` to make HTTP calls
 
-Remember to import this package
-
-Consider using the keyword argument `data`, `json`, and/or `headers`
+Remember to import the `requests` package. Consider using the keyword argument `data`, `json`, and/or `headers`.
 
 #### Tips
-- Remember to put your Slackbot token in your code in an intentional way, following best practices about API keys in code bases.
 - In order to get the value of an environment variable, use `os.environ.get()`, just as we used it for the database configuration.
 - Use your work from the Slack API documentation, the Slack tester, and Postman to guide your implementation.