diff --git a/.DS_Store b/.DS_Store index 15ad7a2..115feff 100644 Binary files a/.DS_Store and b/.DS_Store differ diff --git a/.gitignore b/.gitignore index 62c8b06..c4bed06 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ docs/.DS_Store .DS_Store .DS_Store +.DS_Store diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 0000000..703eaa6 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,21 @@ +# MIT License + +Copyright © 2025 Julie Brodeur and Jeff Naemura + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/docs-planning/info-arch.md b/docs-planning/info-arch.md index 2e41f9d..4f66113 100644 --- a/docs-planning/info-arch.md +++ b/docs-planning/info-arch.md @@ -1,6 +1,6 @@ # Information architecture for orca-sightings-api docs -*Draft 2* +*Draft 3* ## `/docs` @@ -24,7 +24,7 @@ Contains "index" file `tutorials.md`. Also includes: Supporting topics that are reused across other topics: -- `set-up-dev-env.md` → how to set up the development environment +- `set-up-dev-env.md` → how to set up the environment for using tutorials - `start-service.md` → how to start the Orca Sightings service ### `/reference` diff --git a/docs-planning/portfolio-preso-juliebro-v1.pptx b/docs-planning/portfolio-preso-juliebro-v1.pptx new file mode 100644 index 0000000..06d032b Binary files /dev/null and b/docs-planning/portfolio-preso-juliebro-v1.pptx differ diff --git a/docs-planning/portfolio-preso-juliebro-v2.pdf b/docs-planning/portfolio-preso-juliebro-v2.pdf new file mode 100644 index 0000000..f428a60 Binary files /dev/null and b/docs-planning/portfolio-preso-juliebro-v2.pdf differ diff --git a/docs-planning/~$portfolio-preso-juliebro-v1.pptx b/docs-planning/~$portfolio-preso-juliebro-v1.pptx new file mode 100644 index 0000000..358155c Binary files /dev/null and b/docs-planning/~$portfolio-preso-juliebro-v1.pptx differ diff --git a/docs/.DS_Store b/docs/.DS_Store index 44a2a8c..1c2fe08 100644 Binary files a/docs/.DS_Store and b/docs/.DS_Store differ diff --git a/docs/_config.yml b/docs/_config.yml index f8590c6..15c7324 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -16,6 +16,7 @@ nav_enabled: true # The format for this property's value is / # *** DO NOT CHANGE THIS VALUE remote_theme: just-the-docs/just-the-docs + # For information about this theme and its options, see: https://just-the-docs.com/ # # These values describe aspects of the final documentation. How they are @@ -123,9 +124,13 @@ liquid: back_to_top: true back_to_top_text: "Back to top" +# +# favicon for the browser tab +favicon_ico: /images/favicon.png + # # !!! CHANGE THIS VALUE TO APPLY TO YOUR DOCUMENTATION -footer_content: "Copyright © 2025 Julie Brodeur (tech writer) and Jeff Naemura (subject matter expert)." +footer_content: "Copyright © 2025 Julie Brodeur (technical writer) and Jeff Naemura (subject matter expert). Distributed by an MIT license. This work is for educational and demonstration purposes only." # - - - - - - - - - - - - - - - - # @@ -148,7 +153,7 @@ footer_content: "Copyright © 2025 Julie Brodeur (tech writer) and Jeff Naem # in the navigation, where 1 is the first entry, 2 is below 1, etc. # See also https://just-the-docs.com/docs/navigation/main/order/ # -# has_children: true +# has_children: true !!! Note: This is no longer required. # Specifies if this topic has sub-topics. Value can be true or false. # If the topic has sub-topics, the sub-topics must contain the parent # property in their front matter and list the page name of the topic diff --git a/docs/images/favicon.png b/docs/images/favicon.png new file mode 100644 index 0000000..ad16c50 Binary files /dev/null and b/docs/images/favicon.png differ diff --git a/docs/index.md b/docs/index.md index 23de890..7eb1002 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,7 @@ This cloud-based service tracks the movements of orca pods around the San Juan I Using this service, orca enthusiasts can report the location and time of their sightings off the coast of any of the San Juan Islands, making it easy for others to sight these whales from land so they don't have to charter a boat. As a developer, you can include this service in your app. -To get started, learn how to [set up your development environment](./tutorials/set-up-dev-env.md) and [list all sightings](./tutorials/quickstart.md) in the service, or jump down to learn more about the [user community](#user-community) and [features](#features). +To get started, learn how to [set up your environment](./tutorials/set-up-dev-env.md) and [list all sightings](./tutorials/quickstart.md) in the service, or jump down to learn more about the [user community](#user-community) and [features](#features). ![ Photo of orca whales](./images/orca-photo.png) @@ -21,15 +21,12 @@ The orca whale watching community is niche but active. It includes a variety of ## Features -{: .comment } -This section includes links to the relevant tutorials for each action. Most of the links don't work now. - The Orca Sightings service is a RESTful API designed to support this community. It offers two main resources: `/users` and `/sightings`. Each resource supports standard HTTP methods, including GET, POST, PUT, PATCH, and DELETE, so your app can perform the following actions: -- [Create new user profiles](./tutorials/add-user.md) and [log new orca sightings](./tutorials/add-new-sighting.md). -- [Retrieve all or specific user](./tutorials/get-user.md) and [sighting records](./tutorials/get-sighting.md). +- [Create new user profiles](./tutorials/add-user.md) and [log new orca sightings](./tutorials/add-sighting.md). +- [Retrieve all or specific user](./tutorials/list-users.md) and [sighting records](./tutorials/quickstart.md). - [Update existing user information](./tutorials/update-user.md) and [sighting details](./tutorials/update-sighting.md). - [Delete user accounts](./tutorials/delete-user.md) and [sighting entries](./tutorials/delete-sighting.md). -{: .warning } +{: .note } This is a simulated REST interface only for the demonstration of API documentation. diff --git a/docs/reference/sightings/sightings-delete.md b/docs/reference/sightings/sightings-delete.md index 16c54dc..27285a4 100644 --- a/docs/reference/sightings/sightings-delete.md +++ b/docs/reference/sightings/sightings-delete.md @@ -30,11 +30,11 @@ Also see: - [Base URL](../base-url.md) -## Parameters +## Properties Required: the `id` of the user you want to delete. Specify this in the endpoint. -For a full description of all `/sightings` properties, see [`/sightings` resource](./sightings-resource.md#parameters). +For a full description of all `/sightings` properties, see [`/sightings` resource](./sightings-resource.md#properties). ## Request body diff --git a/docs/reference/sightings/sightings-get.md b/docs/reference/sightings/sightings-get.md index 245e056..60c2af6 100644 --- a/docs/reference/sightings/sightings-get.md +++ b/docs/reference/sightings/sightings-get.md @@ -32,11 +32,11 @@ Also see: - [Base URL](../base-url.md) -## Parameters +## Properties Optional: the `id` of a specific sighting to list. -For a full description of all `/sightings` properties, see [`/sightings` resource](./sightings-resource.md#parameters). +For a full description of all `/sightings` properties, see [`/sightings` resource](./sightings-resource.md#properties). ## Headers diff --git a/docs/reference/sightings/sightings-patch.md b/docs/reference/sightings/sightings-patch.md index c600126..b78db70 100644 --- a/docs/reference/sightings/sightings-patch.md +++ b/docs/reference/sightings/sightings-patch.md @@ -27,13 +27,13 @@ Also see: `{base_url}/sightings/{id}` -## Parameters +## Properties Required: specify a sighting `id`. Optional, but you should include at least one: `user_id`, `pod`, `time`, and `location`. -For a description of these properties, see [`/sightings` resource](./sightings-resource.md#parameters). +For a description of these properties, see [`/sightings` resource](./sightings-resource.md#properties). ## Headers diff --git a/docs/reference/sightings/sightings-post.md b/docs/reference/sightings/sightings-post.md index 7ec8b19..58699da 100644 --- a/docs/reference/sightings/sightings-post.md +++ b/docs/reference/sightings/sightings-post.md @@ -31,13 +31,13 @@ Also see: - [Base URL](../base-url.md) -## Parameters +## Properties Optional, but recommended: `user_id`, `pod`, `time`, and `location`. The service automatically assigns the new user a unique `id`. > If you don't include any data in your request, the server creates an empty sighting with a unique ID. -For a description of these parameters, see [`/sightings` resource](./sightings-resource.md#parameters). +For a description of these properties, see [`/sightings` resource](./sightings-resource.md#properties). ## Headers diff --git a/docs/reference/sightings/sightings-put.md b/docs/reference/sightings/sightings-put.md index 09cf3fa..8442563 100644 --- a/docs/reference/sightings/sightings-put.md +++ b/docs/reference/sightings/sightings-put.md @@ -29,16 +29,16 @@ Also see: - [Base URL](../base-url.md) -## Parameters +## Properties Required: specify the `id` of the sighting you want to update in the endpoint. -Optional: you should include all: you can use the following parameters to update a sighting: `user_id`, `pod`, `time`, and `location`. +Optional: you should include all: you can use the following properties to update a sighting: `user_id`, `pod`, `time`, and `location`. {: .note } If you don't include the full data in your request, the server creates the sighting again with no data in that field. Likewise, if you don't include any data in your request, the server creates an empty sighting with the existing ID. -For a description of these parameters, see [`/sightings` resource](./sightings-resource.md#parameters). +For a description of these properties, see [`/sightings` resource](./sightings-resource.md#properties). ## Headers diff --git a/docs/reference/sightings/sightings-resource.md b/docs/reference/sightings/sightings-resource.md index 7e495f2..6b110b0 100644 --- a/docs/reference/sightings/sightings-resource.md +++ b/docs/reference/sightings/sightings-resource.md @@ -23,7 +23,7 @@ Also see the [`/users` resource](../users/users-resource.md). Also see [Base URL](../base-url.md) -## Parameters +## Properties Example of a full `/sightings` resource: @@ -37,12 +37,12 @@ Example of a full `/sightings` resource: } ``` -Description of resource parameters: +Description of resource properties: -| Parameter | Type | Description | Example | +| Property | Type | Description | Example | | ---------- | --------- | ------------------------------------------------------------ | ------------------------------ | | `id` | `integer` | Unique identifier for the sighting. Read-only and automatically generated. | `1` | -| `user_id` | `integer` | The ID of the user who reported the sighting, as described in the [`/users` resource](../users-resource/users-resource.md). | `1` | +| `user_id` | `integer` | The ID of the user who reported the sighting, as described in the [`/users` resource](../users/users-resource.md). | `1` | | `pod` | `string` | The identified pod of orca. Available attributes are `J-pod`, `K-pod`, `T49A`, and `unknown`). | `"J-pod"` | | `time` | `string` | The timestamp of the sighting in [ISO 8601 format](../iso-8601-format.md). | `"2025-05-03T10:00"` | | `location` | `string` | The location where the sighting occurred. | `"Lime Kiln Point State Park"` | diff --git a/docs/reference/users/users-delete.md b/docs/reference/users/users-delete.md index 967d532..dff7324 100644 --- a/docs/reference/users/users-delete.md +++ b/docs/reference/users/users-delete.md @@ -34,11 +34,11 @@ Also see: `Content-Type: application/json` -## Parameters +## Properties Required: the `id` of the user you want to delete. Specify this in the endpoint. -For a full description of all `/users` properties, see [`/users` resource](./users-resource.md#parameters). +For a full description of all `/users` properties, see [`/users` resource](./users-resource.md#properties). ## Request body diff --git a/docs/reference/users/users-get.md b/docs/reference/users/users-get.md index c922503..b5e619c 100644 --- a/docs/reference/users/users-get.md +++ b/docs/reference/users/users-get.md @@ -28,11 +28,11 @@ Also see: - [Base URL](../base-url.md) -## Parameters +## Properties Optional: the `id` of a specific user to list. -For a description of all parameters, see [`/users` resource](./users-resource.md#parameters). +For a description of all properties, see [`/users` resource](./users-resource.md#properties). ## Request body diff --git a/docs/reference/users/users-patch.md b/docs/reference/users/users-patch.md index df5878c..6797bd2 100644 --- a/docs/reference/users/users-patch.md +++ b/docs/reference/users/users-patch.md @@ -10,7 +10,7 @@ nav_order: 4 - TOC {:toc} -# `PATCH /users`: Update some of the details about a user +# `PATCH /users` update some of the details about a user Updates some of the details about a user. @@ -19,7 +19,7 @@ Also see: - [Update all or part of a user entry: a tutorial](../../tutorials/update-user.md) - [GET: List all users](./users-get.md) - [GET: Get user by id](./users-get.md) -- [PATCH: Update part of a sighting](../sightings-resource/sightings-patch.md) +- [PATCH: Update part of a sighting](../sightings/sightings-patch.md) ## Method @@ -33,11 +33,11 @@ Also see: - [Base URL](../base-url.md) -## Parameters +## Properties Required: the `id` of the user you want to update. -For a description of all parameters, see [`/users` resource](./users-resource.md#parameters). +For a description of all properties, see [`/users` resource](./users-resource.md#properties). ## Headers diff --git a/docs/reference/users/users-post.md b/docs/reference/users/users-post.md index 0f3b5d0..63f381c 100644 --- a/docs/reference/users/users-post.md +++ b/docs/reference/users/users-post.md @@ -30,11 +30,11 @@ Also see: - [Base URL](../base-url.md) -## Parameters +## Properties -Optional, you should include all: `first_name`, `last_name`, and `email`. The service automatically assigns the new user a unique `id`. +Optional, but you should include all: `first_name`, `last_name`, and `email`. The service automatically assigns the new user a unique `id`. -For a description of these properties, see [`/users` resource](./users-resource.md#parameters). +For a description of these properties, see [`/users` resource](./users-resource.md#properties). ## Headers @@ -44,7 +44,7 @@ For a description of these properties, see [`/users` resource](./users-resource. ### cURL example -Shows creating a new user named Ben Waters. +Creates a new user named Ben Waters. ```shell curl -X POST \ @@ -55,7 +55,7 @@ curl -X POST \ ### Postman example -Shows creating a new user named Ben Waters. +Creates a new user named Ben Waters. #### Request builder method and endpoint diff --git a/docs/reference/users/users-put.md b/docs/reference/users/users-put.md index beee8c5..8572e76 100644 --- a/docs/reference/users/users-put.md +++ b/docs/reference/users/users-put.md @@ -28,7 +28,7 @@ Updates the entire user record for the specified `id`. Also see: - [Base URL](../base-url.md) -## Parameters +## Properties Required: the `id` of the user you want to update. @@ -37,7 +37,7 @@ Optional, you should include all: `first_name`, `last_name`, and `email`. {: .warning } If you don't include this data in your request, the server creates the user again with no data in that field. Likewise, if you don't include any data in your request, the server creates an empty user with the existing ID. -For a description of these properties, see [`/users` resource](./users-resource.md#parameters). +For a description of these properties, see [`/users` resource](./users-resource.md#properties). ## Headers diff --git a/docs/reference/users/users-resource.md b/docs/reference/users/users-resource.md index 0176032..f52cf69 100644 --- a/docs/reference/users/users-resource.md +++ b/docs/reference/users/users-resource.md @@ -23,7 +23,7 @@ Also see [`/sightings` resource](../sightings/sightings-resource.md). Also see [Base URL](../base-url.md). -## Parameters +## Properties Shows an example of a full `/users` resource: @@ -36,9 +36,9 @@ Shows an example of a full `/users` resource: } ``` -Describes all parameters available in the `/users` resource: +Describes all properties available in the `/users` resource: -| Parameter | Type | Description | Example | +| Property | Type | Description | Example | | ------------ | --------- | ------------------------------------------------------------ | ------------------------ | | `last_name` | `string` | The user's last name. | `"Marsh"` | | `first_name` | `string` | The user's first name. | `"Stan"` | diff --git a/docs/tutorials/add-sighting.md b/docs/tutorials/add-sighting.md new file mode 100644 index 0000000..60fd76a --- /dev/null +++ b/docs/tutorials/add-sighting.md @@ -0,0 +1,87 @@ +--- +layout: default +title: Add a new sighting +parent: Tutorials +nav_order: 8 +--- + +**On this page:** + +- TOC +{:toc} + +# Add a new sighting to the Orca Sightings service: a tutorial + +This tutorial should take you about 15 minutes to complete. + +## Before you begin + +Make sure you've [set up your environment](./set-up-dev-env.md) and [started the service using `json-server`](./start-service.md). + +## Step 1: Submit a cURL or Postman request with the POST method + +**To use cURL:** + +Enter the following command to add a new sighting reported by the user with an `id` of `1`. + +```shell +curl -X POST \ + -H "Content-Type: application/json" \ + -d '{ "user_id": 1, "pod": "K-pod", "time": "2024-12-24T09:20", "location": "Friday Harbor" }' \ + http://localhost:3000/sightings +``` + +In this example, -X specifies the method, -H indicates the header, and -d specifies the data. + +For `user_id`, you specify `1` to pair the sighting with the first user. This is the person who reported the sighting. + +Try using GET to see user 1: + +```shell +curl -X GET http://localhost:3000/users/1 +``` + +The result shows the user as Stan Marsh: + +```json +{ + "last_name": "Marsh", + "first_name": "Stan", + "email": "stan.marsh@gmail.com", + "id": 1 +} +``` + +**To use Postman:** + +1. Select **POST** and enter `http://localhost:3000/sightings/`. +2. In the **Header** tab, select **Content-Type** and then **application/json**. +3. In the request body, select **Body > raw > JSON** and enter: + +```json +{ + "user_id": 1, + "pod": "K-pod", + "time": "2024-12-24T09:20", + "location": "Friday Harbor" +} +``` + +## Step 2: Make sure the service created the new sighting + +Both of the previous examples should return the information from the request body plus a unique ID. + +```json +{ + "user_id": 1, + "pod": "K-pod", + "time": "2024-12-24T09:20", + "location": "Friday Harbor", + "id": 6 +} +``` + +{: .note } +The `id` might be different if you've completed other tutorials first. + +You've completed this tutorial. Next, try other [tutorials](./tutorials.md) or refer to the reference topic [POST /sightings](../reference/sightings/sightings-post.md). diff --git a/docs/tutorials/add-user.md b/docs/tutorials/add-user.md index a322182..3aaff93 100644 --- a/docs/tutorials/add-user.md +++ b/docs/tutorials/add-user.md @@ -2,7 +2,7 @@ layout: default title: Add a new user parent: Tutorials -nav_order: 4 +nav_order: 5 --- **On this page:** @@ -12,44 +12,55 @@ nav_order: 4 # Add a new user to the Orca Sightings service: a tutorial -{: .comment } -This page is in progress. - This tutorial should take you about 15 minutes to complete. -Also see the API reference pages: - -- [PUT /users](../reference/users-resource/users-put.md) -- [PATCH /users](../reference/users-resource/users-patch.md) - ## Before you begin -Make sure you've [set up your development environment](./set-up-dev-env.md). +Make sure you've [set up your environment](./set-up-dev-env.md) and [started the service using `json-server`](./start-service.md). -## Step 1: Start the Orca Sightings service +## Step 1: Submit a cURL or Postman request with the POST method -1. Open a terminal window and cd to the location of `json-server`. +**To use cURL:** -2. Start the service by typing `json-server orca-sightings-db.json`. The service starts and lists some information to show it's running. +Enter the following command to add a new user named Ben Waters. ```shell +curl -X POST \ + -H "Content-Type: application/json" \ + -d '{ "last_name": "Waters", "first_name": "Ben", "email": "ben.waters@gmail.com" }' \ + http://localhost:3000/users +``` + +In this example, -X specifies the method, -H indicates the header, and -d specifies the data. + +**To use Postman:** + +1. Select **POST** and enter `http://localhost:3000/users/`. +2. In the **Header** tab, select **Content-Type** and then **application/json**. +3. In the request body, select **Body > raw > JSON** and enter: + +```json +{ + "last_name": "Waters", + "first_name": "Ben", + "email": "ben.waters@gmail.com" +} +``` + +## Step 2: Make sure the service created the new user -user@macbookair ~ % json-server orca-sightings-db.json - -\{^_^}/ hi! - -Loading orca-sightings-db.json -Done - -Resources -http://localhost:3000/users -http://localhost:3000/sightings - -Home -http://localhost:3000 +Both of the previous examples should return the information from the request body plus a unique ID. +```json +{ + "last_name": "Waters", + "first_name": "Ben", + "email": "ben.waters@gmail.com", + "id": 5 +} ``` -## Step 2: Open Postman +{: .note } +The `id` might be different if you've completed other tutorials first. -> Info to come. +You've completed this tutorial. Next, try other [tutorials](./tutorials.md) or refer to the reference topic [POST /users](../reference/users/users-post.md). diff --git a/docs/tutorials/delete-sighting.md b/docs/tutorials/delete-sighting.md new file mode 100644 index 0000000..2b90903 --- /dev/null +++ b/docs/tutorials/delete-sighting.md @@ -0,0 +1,62 @@ +--- +layout: default +title: Delete a sighting +parent: Tutorials +nav_order: 10 +--- + +**On this page:** + +- TOC +{:toc} + +# Delete a sighting: a tutorial + +This tutorial should take you about 10 minutes to complete. + +## Before you begin + +1. Make sure you've [set up your environment](./set-up-dev-env.md). +2. [Start the Orca Sightings service](./start-service.md) with `json-server`. + +## How to delete a sighting + +In this section, you'll delete the sighting with an `id` of `4`. + +{: .note } +To list all sightings and pick a different sighting to delete, refer to [Get started by listing orca sightings: a tutorial](./quickstart.md) + +**To use cURL:** + +1. Open a new terminal window. +2. Run the following command: + +```shell +curl -X DELETE http://localhost:3000/sightings/4 +``` + +{: .tip } +The `4` at the end of the URL specifies the sighting ID. + +**To use Postman:** + +1. In Postman's main panel on the right, toward the top, select **DELETE**. +2. Add the following content to the URL text box next to GET: `http://localhost:3000/sightings/4`. +3. Click **Send**. + +{: .note } +If you don't specify a sighting ID, the service won't delete all the sightings. Instead, it returns a **404 Not Found** error message. + +## View the response + +The response body should show an empty record: + +```json +{} +``` + +In Postman, you should also see a green 200 OK message at the top of the pane. Hover over that text to see the full confirmation message. + +That's it. Next, view the reference topic [`DELETE /sightings`](../reference/sightings/sightings-delete.md). + +Also, you can try other [tutorials](./tutorials.md) or view other topics in the [API reference](../reference/api-reference.md). diff --git a/docs/tutorials/delete-user.md b/docs/tutorials/delete-user.md new file mode 100644 index 0000000..dca4772 --- /dev/null +++ b/docs/tutorials/delete-user.md @@ -0,0 +1,57 @@ +--- +layout: default +title: Delete a user +parent: Tutorials +nav_order: 7 +--- + +**On this page:** + +- TOC +{:toc} + +# Delete a user: a tutorial + +This tutorial should take you about 10 minutes to complete. + +## Before you begin + +1. Make sure you've [set up your environment](./set-up-dev-env.md). +2. [Start the Orca Sightings service](./start-service.md) with `json-server`. + +## How to delete a user + +In this section, you'll delete the user with an `id` of `4`. + +**To use cURL:** + +1. Open a new terminal window. +2. [Find the user](./list-users.md) you want to delete. +3. Run the following command: + +```shell +curl -X DELETE http://localhost:3000/users/4 +``` + +**To use Postman:** + +1. In Postman's main panel on the right, toward the top, select **DELETE**. +2. Add the following content to the URL text box next to GET: `http://localhost:3000/users/4`. +3. Click **Send**. + +{: .note } +If you don't specify a user ID, the service won't delete all the users. Instead, it returns a **404 Not Found** error message. + +## View the response + +The response body should show an empty record: + +```json +{} +``` + +In Postman, you should also see a green 200 OK message at the top of the pane. Hover over that text to see the full confirmation message. + +That's it. Next, view the reference topic [`DELETE /users`](../reference/users/users-delete.md). + +Also, you can try other [tutorials](./tutorials.md) or view other topics in the [API reference](../reference/api-reference.md). diff --git a/docs/tutorials/list-users.md b/docs/tutorials/list-users.md new file mode 100644 index 0000000..2813591 --- /dev/null +++ b/docs/tutorials/list-users.md @@ -0,0 +1,76 @@ +--- +layout: default +title: List users +parent: Tutorials +nav_order: 4 +--- + +**On this page:** + +- TOC +{:toc} + +# List all or some users: a tutorial + +This tutorial should take you about 15 minutes to complete. + +## Before you begin + +1. Make sure you've [set up your environment](./set-up-dev-env.md). +2. [Start the Orca Sightings service](./start-service.md) with `json-server`. + +## How to list all users + +**To use cURL:** + +1. Open a new terminal window. +2. Run the following command: + +```shell +curl -X GET http://localhost:3000/users/ +``` + +**To use Postman:** + +1. In Postman's main panel on the right, toward the top, select **GET**. +2. Add the following content to the URL text box next to GET: `http://localhost:3000/users/`. +3. Click **Send**. + +## View the response + +The response body should show all users and look like this: + +```json +[ + { + "last_name": "Marsh", + "first_name": "Stan", + "email": "stan.marsh@gmail.com", + "id": 1 + }, + { + "last_name": "Broflovski", + "first_name": "Kyle", + "email": "kyle.broflovski@yahoo.com", + "id": 2 + }, + { + "last_name": "Cartman", + "first_name": "Eric", + "email": "eric.cartman@hotmail.com", + "id": 3 + }, + { + "last_name": "McCormick", + "first_name": "Kenny", + "email": "kenny.mccormick@gmail.com", + "id": 4 + } +] +``` + +In Postman, you should also see a green 200 OK message at the top of the pane. Hover over that text to see the full confirmation message. + +That's it. Next, view the reference topic [`GET /users`](../reference/users/users-get.md) to see an example of listing a specific user by its `id`. + +Also, you can try other [tutorials](./tutorials.md) like [adding a user](./add-user.md) or view other topics in the [API reference](../reference/api-reference.md). diff --git a/docs/tutorials/quickstart.md b/docs/tutorials/quickstart.md index 27988db..43b79da 100644 --- a/docs/tutorials/quickstart.md +++ b/docs/tutorials/quickstart.md @@ -2,7 +2,7 @@ layout: default title: Get started by listing orca sightings parent: Tutorials -nav_order: 2 +nav_order: 3 --- **On this page:** @@ -12,23 +12,21 @@ nav_order: 2 # Get started by listing orca sightings: a tutorial -This tutorial shows you how to download the API files and try one of the service actions: viewing all orca sightings reported in the app for the San Juan Islands. If you've already [set up your development environment](./set-up-dev-env.md), the process should take about 20 minutes. +This tutorial shows you how to download the API files and try one of the service actions: viewing all orca sightings reported in the app for the San Juan Islands. If you've already [set up your environment](./set-up-dev-env.md), the process should take about 20 minutes. -## Step 1: Make sure you have the API files +## Step 1: Make sure you have the API database file -The files are located in the [orca-sightings-api repo on GitHub](https://github.com/juliebro/orca-sightings-api/tree/main/api). The directory contains the following files: +If you haven't already done so: -- `orca-sightings-db.json`: a JSON file containing example users and sightings. -- `orca-sightings.sh`: a shell script that starts JSON Server. Use this for Linux or macOS. -- `orca-sightings.bat`: a batch file that starts JSON Server. Use this for Windows. +1. Download `orca-sightings-db.json`. The file is at [orca-sightings-api repo on GitHub](https://github.com/juliebro/orca-sightings-api/tree/main/api). This is a JSON file containing example users and sightings. +2. Copy this file into the same location as your `json-server` app. ## Step 2: Start JSON Server with the Orca Sightings service To start the Orca Sightings service: 1. Open a terminal window and `cd` to the location of the `json-server` app. -2. Make sure you intall the API files in the same directory. If they aren't, copy or move them now. -3. Start the service by typing `json-server orca-sightings-db.json`. The service starts and lists some information to show it's running. +2. Start the service by typing `json-server orca-sightings-db.json`. The service starts and lists some information to show it's running. ```shell user@macbookair ~ % json-server orca-sightings-db.json @@ -51,21 +49,20 @@ To start the Orca Sightings service: In this part of the tutorial, you'll use cURL or Postman to list all orca whale sightings. -### If you're using cURL +**To use cURL:** -1. Open a terminal window. +1. Open a new terminal window. 2. Run this command: ```shell curl -X GET http://localhost:3000/sightings ``` -### If you're using Postman +**To use Postman:** -1 In Postman's main panel on the right, toward the top, select **GET**. -2. Add the following content to the URL text box next to GET: `http://localhost:3000/users/`. -3. If you don't already have the header designated, choose **Headers** and specify **Content-Type: application/json**. -4. Click **Send**. +1. In Postman's main panel on the right, toward the top, select **GET**. +2. Add the following content to the URL text box next to GET: `http://localhost:3000/sightings/`. +3. Click **Send**. ## Step 4: View the response @@ -136,4 +133,4 @@ In Postman, you should also see a green 200 OK message at the top of the pane. H That's it. Next, view the reference topic [`GET /sightings`](../reference/sightings/sightings-get.md) to see an example of listing a specific sighting by its `id`. -Also, you can try other [tutorials](./tutorials.md) like [adding a user](./add-user.md) or view other topics in the [API reference](../reference/api-reference.md). +You can also try other [tutorials](./tutorials.md) like [adding a user](./add-user.md) or view other topics in the [API reference](../reference/api-reference.md). diff --git a/docs/tutorials/set-up-dev-env.md b/docs/tutorials/set-up-dev-env.md index 56cd295..c3379fd 100644 --- a/docs/tutorials/set-up-dev-env.md +++ b/docs/tutorials/set-up-dev-env.md @@ -1,6 +1,6 @@ --- layout: default -title: Set up your dev environment +title: Set up your environment parent: Tutorials nav_order: 1 --- @@ -10,13 +10,13 @@ nav_order: 1 - TOC {:toc} -# Set up your development environment: a tutorial +# Set up your environment: a tutorial > Adapted from [To-do service API: Before you start a tutorial](https://uwc2-apidoc.github.io/to-do-service-sp25/before-you-start-a-tutorial.html). ## Overview -Before you begin using the Orca Sightings service, you must set up your development environment. +Before you begin using the Orca Sightings service, you must set up your environment. Expect this to take about 30 minutes to complete. @@ -28,20 +28,24 @@ Install the following software on your desktop, which should run a recent versio - A recent version of **[json-server](https://www.npmjs.com/package/json-server)**. - The [**Postman desktop app**](https://www.postman.com/downloads/). You’ll run the Orca Sightings service on your local development system, so the web version of Postman won’t work. The default port for localhost is 3000: `http://localhost:3000/` -## Step 2: Download the relevant files from GitHub +## Step 2: Download the database file from GitHub -Download a current copy of the **database file** and the relevant **startup script**. You can [download these from the Orca Sightings service repository on GitHub](https://github.com/juliebro/orca-sightings-api/tree/main/api). +Download a current copy of the database file `orca-sightings-db.json` from [the Orca Sightings service repository on GitHub](https://github.com/juliebro/orca-sightings-api/tree/main/api). -To download each file: +To download the file: -1. Hover over a filename and click the link that appears. +1. Hover over `orca-sightings-db.json` and click the link that appears. 2. On the upper right side of the panel, click the download button, a down arrow. -3. Do this for the `orca-sightings-db.json` file and one of the startup scripts: `orca-sightings.sh` for macOS and Linux or `start-server.bat` for Windows. +3. Copy this file to the same location as your `json-server` app. ## Step 3: Run JSON Server with the `orca-sightings-db.json` file -1. Go to the directory on your computer where you downloaded `orca-sightings-db.json` and the relevant start script. -2. On Windows, double-click the `start-server.bat` file to start the service. On macOS or Linux, open a terminal window, `cd` to the directory where you downloaded the files, and type `./orca-sightings.sh`. That runs the script in the current directory. If that doesn't work, type `json-server orca-sightings-db.json`. You should see some text like this that shows the service is running: +To start the Orca Sightings service: + +1. Open a terminal window and `cd` to the location of the `json-server` app. +2. Start the service by typing `json-server orca-sightings-db.json`. The service starts and lists some information to show it's running. + +You should see some text like this that shows the service is running: ```shell @@ -66,7 +70,9 @@ Use cURL or Postman to test the service. ### Using cURL - +```shell +curl -X GET http://localhost:3000/users/4 +``` ### Using Postman @@ -114,4 +120,4 @@ If you receive an error in any step of the procedure, investigate, and correct t - A required software component didn't install correctly. - A required software component isn't up to date. -If you see the list of users from the service, you're ready to start the [Tutorials](./tutorials/tutorials.md). +If you see the list of users from the service, you're ready to start the [Tutorials](./tutorials.md). diff --git a/docs/tutorials/start-service.md b/docs/tutorials/start-service.md index 32ac99a..0c7586a 100644 --- a/docs/tutorials/start-service.md +++ b/docs/tutorials/start-service.md @@ -2,18 +2,17 @@ layout: default title: Start the service parent: Tutorials -nav_order: 3 +nav_order: 2 --- -# Start the Orca Sightings service +# Start the Orca Sightings service: a tutorial To start the Orca Sightings service: 1. Open a terminal window and `cd` to the location of the `json-server` app. - 2. Start the service by typing `json-server orca-sightings-db.json`. The service starts and lists some information to show it's running. - ```shell +```shell user@macbookair ~ % json-server orca-sightings-db.json \{^_^}/ hi! @@ -27,6 +26,6 @@ To start the Orca Sightings service: Home http://localhost:3000 - ``` +``` -Also see [Tutorials](./tutorials.md). +Also see more [Tutorials](./tutorials.md) or the [API reference](../reference/api-reference.md). diff --git a/docs/tutorials/update-sighting.md b/docs/tutorials/update-sighting.md new file mode 100644 index 0000000..75145d3 --- /dev/null +++ b/docs/tutorials/update-sighting.md @@ -0,0 +1,189 @@ +--- +layout: default +title: Update a sighting +parent: Tutorials +nav_order: 9 +--- + +**On this page:** + +- TOC +{:toc} + +# Update a sighting: a tutorial + +This tutorial should take you about 20 minutes to complete. + +## Before you begin + +1. Make sure you've [set up your environment](./set-up-dev-env.md). +2. If it's not already running, [start the Orca Sightings service](./start-service.md) with json-server. + +## How to update the full sighting entry + +Use the PUT method to update a full sighting entry. + +### Step 1: list all sightings to find the `id` of the sighting you want to update + +You can use cURL or Postman to submit a PUT request. + +**To use cURL:** + +1. Open a new terminal window. +2. [List all sightings](./quickstart.md#step-3-list-orca-whale-sightings). Notice the sighting entry with an `id` of `2`. + +```json +... +{ + "id": 2, + "user_id": 3, + "pod": "T49A", + "time": "2025-05-01T19:00", + "location": "Patos Island" +}, +... +``` + +**To use Postman:** + +1. Open Postman. +2. [List all sightings](./quickstart.md#step-3-list-orca-whale-sightings). Notice the sighting entry with an `id` of `2`. + +```json +... +{ + "id": 2, + "user_id": 3, + "pod": "T49A", + "time": "2025-05-01T19:00", + "location": "Patos Island" +}, +... +``` + +### Step 2: replace the entire entry using the PUT method + +**To use cURL:** + +1. Include that information in a cURL request, changing the pod to `unknown`. Don't include the `id` in the `-d` field. Instead, include that number at the end of the URL. This is the *endpoint*. + +```shell +curl -X PUT \ + -H "Content-Type: application/json" \ + -d '{ + "user_id": 3, + "pod": "unknown", + "time": "2025-05-01T19:00", + "location": "Patos Island" + }' \ + http://localhost:3000/sightings/2 +``` + +In the cURL command, `-X` denotes the method to use, `-H` indicates the header to use, and `-d` specifies the data to include. + +{: .tip } +The `user_id` isn't the same as the `id`. The latter refers to the sighting ID, which you add to the end of the URL. The former pairs the sighting with the user who reported it. + +The output should look like the following: + +```shell +{ + "user_id": 3, + "pod": "unknown", + "time": "2025-05-01T19:00", + "location": "Patos Island" + "id": 2, +} +``` + +**To use Postman:** + +1. In Postman's main panel on the right, toward the top, select **PUT**. +2. Add the following content to the URL text box next to PUT: `http://localhost:3000/sightings/2`. This indicates that you'll replace the information for the user that has an ID of 2. +3. If you don't already have the header designated, choose **Headers** and specify **Content-Type: application/json**. +4. Choose **Body** and specify **Raw**. +5. Copy the following example code that changes the pod to `unknown.` Paste this into Postman's **Body** text box. + +```json +{ + "user_id": 3, + "pod": "unknown", + "time": "2025-05-01T19:00", + "location": "Patos Island" +} +``` + +{: .note } +Notice that you don't need the ID. Enter it in Postman's URL parameters. You must remove the trailing comma in the last key-value pair. + +Notice that the response includes the entire entry details with the ID. + +```json +{ + "user_id": 3, + "pod": "unknown", + "time": "2025-05-01T19:00", + "location": "Patos Island" + "id": 2, +} +``` + +## How to update only part of the entry + +Update just a part of the user entry using the PATCH method. Choose the same sighting as in the previous example with an `id` of `2`. You'll update just the time. + +**To use cURL:** + +Send a request using cURL with the following command: + +```shell +curl -X PATCH \ + -H "Content-Type: application/json" \ + -d '{ "time": "2025-05-01T08:00" }' \ + http://localhost:3000/sightings/2 +``` + +Notice that the `time` value, which follows the `T` is now 8:00 AM: `08:00`. + +{: .note} +For a full description of the time value, refer to [ISO 8601 format](../reference/sightings/iso-8601-format.md). + +Notice that the response includes the entire entry details with the updated time. + +```shell +{ + "user_id": 3, + "pod": "unknown", + "time": "2025-05-01T08:00", + "location": "Patos Island" + "id": 2, +} +``` + +**To use Postman:** + +1. In Postman's main panel on the right, toward the top, select **PATCH**. +2. Add the following content to the URL text box next to PATCH: `http://localhost:3000/sightings/2`. This indicates that you'll update some information for the sighting that has an ID of `2`. +3. If you don't already have the header designated, choose **Headers** and specify **Content-Type: application/json**. +4. Choose **Body** and specify **Raw**. +5. Copy the following example code that changes the time `...T19:00` to 8:00 AM: `...T08:00`. Paste the following into Postman's **Body** text box. + +```json +{ + "time": "2025-05-01T08:00" +} +``` + +Notice that the response includes the entire entry details with the updated time. + +```json +{ + "user_id": 3, + "pod": "unknown", + "time": "2025-05-01T08:00", + "location": "Patos Island" + "id": 2, +} +``` + +You've completed this tutorial. Next try other [tutorials](./tutorials.md) or refer to the [PUT](../reference/sightings/sightings-put.md) and [PATCH](../reference/sightings/sightings-patch.md) reference topics. diff --git a/docs/tutorials/update-user.md b/docs/tutorials/update-user.md index fb1445d..b42bbd1 100644 --- a/docs/tutorials/update-user.md +++ b/docs/tutorials/update-user.md @@ -2,7 +2,7 @@ layout: default title: Update a user parent: Tutorials -nav_order: 5 +nav_order: 6 --- **On this page:** @@ -12,27 +12,49 @@ nav_order: 5 # Update a user: a tutorial -{: .comment } -This page is in progress. - This tutorial should take you about 25 minutes to complete. Also see the API reference pages: -- [PUT /users](../reference/users-resource/users-put.md) -- [PATCH /users](../reference/users-resource/users-patch.md) +- [PUT /users](../reference/users/users-put.md) +- [PATCH /users](../reference/users/users-patch.md) ## Before you begin -1. Make sure you've [set up your development environment](./set-up-dev-env.md). +1. Make sure you've [set up your environment](./set-up-dev-env.md). 2. [Start the Orca Sightings service](./start-service.md) with json-server. ## How to update the full user entry -In this part of the tutorial, you'll use the PUT method to update a full user entry. +Use the PUT method to update a full user entry. + +### Step 1: list all users to find the `id` of the user you want to update + +You can use cURL or Postman to submit a PUT request. + +**To use cURL:** + +1. Open a new terminal window. +2. [List all users](./list-users.md). Notice the user entry with an `id` of `4`. +3. Include that information in a cURL request, changing the first name to `Ken` and the email to `ken.mccormick@gmail.com`: + +```shell +curl -X PUT \ + -H "Content-Type: application/json" \ + -d '{ "last_name": "McCormick", "first_name": "Ken", "email": "ken.mccormick@gmail.com" }' \ + http://localhost:3000/users/4 +``` + +In the cURL command, `-X` denotes the method to use, `-H` indicates the header to use, and `-d` specifies the data to include. + +{: .comment } +Do I need to include the `id` jn a `PUT` request, or only include it in the endpoint? + +**To use Postman:** 1. Open Postman. -2. [List all users](./list-users.md) to find which one you want to update. In the this example, you'll choose **Kenny McCormick**. Notice that this user has an `id` of `4`. You'll use that value later on. +2. [List all users](./list-users.md). +3. In the this example, you'll choose **Kenny McCormick**. Notice that this user has an `id` of `4`. You'll use that value later on. ```json [ @@ -63,24 +85,24 @@ In this part of the tutorial, you'll use the PUT method to update a full user en ] ``` -In this part of the tutorial, you'll replace the entire entry using the PUT method. +### Step 2: replace the entire entry using the PUT method 1. In Postman's main panel on the right, toward the top, select **PUT**. 2. Add the following content to the URL text box next to PUT: `http://localhost:3000/users/4`. This indicates that you'll replace the information for the user that has an ID of 4. 3. If you don't already have the header designated, choose **Headers** and specify **Content-Type: application/json**. 4. Choose **Body** and specify **Raw**. -5. Copy the new example code that changes the name **Kenny** to **Ken** in the `first_name` and `email` properties. Paste this into Postman's **Body** text box. - -{: .note } -Notice that you don't need the ID. You'll enter it in Postman's URL text box. You do need to remove the trailing comma in the last key-value pair. +5. Copy the following example code that changes the name **Kenny** to **Ken** in the `first_name` and `email` properties. Paste this into Postman's **Body** text box. ```json { "last_name": "McCormick", "first_name": "Ken", "email": "ken.mccormick@gmail.com" - } - ``` +} +``` + +{: .note } +Notice that you don't need the ID. Enter it in Postman's URL parameters. You must remove the trailing comma in the last key-value pair. Notice that the response includes the entire entry details with the ID. @@ -90,9 +112,58 @@ Notice that the response includes the entire entry details with the ID. "first_name": "Ken", "email": "ken.mccormick@gmail.com", "id": 4 - } +} ``` -## How to update part of the entry +## How to update only part of the entry + +Update just a part of the user entry using the PATCH method. We'll choose the user with an `id` of `1` to update. + +**To use cURL:** + +Send a request using cURL with the following command: + +```shell +curl -X PATCH \ + -H "Content-Type: application/json" \ + -d '{ "email": "stan@example.com" }' \ + http://localhost:3000/users/1 +``` + +Notice that the response includes the entire entry details with the updated email. + +```shell +{ + "last_name": "Marsh", + "first_name": "Stan", + "email": "stan@example.com", + "id": 1 +} +``` + +**To use Postman:** + +1. In Postman's main panel on the right, toward the top, select **PATCH**. +2. Add the following content to the URL text box next to PATCH: `http://localhost:3000/users/1`. This indicates that you'll update some information for the user that has an ID of 1. +3. If you don't already have the header designated, choose **Headers** and specify **Content-Type: application/json**. +4. Choose **Body** and specify **Raw**. +5. Copy the following example code that changes the email **stan.marsh@gmail.com** to **stan@example.com** in the `email` property. Paste this into Postman's **Body** text box. + +```json +{ + "email": "stan@example.com" +} +``` + +Notice that the response includes the entire entry details with the updated email. + +```json +{ + "last_name": "Marsh", + "first_name": "Stan", + "email": "stan@example.com", + "id": 1 +} +``` -In this part of the tutorial, you'll update just a part of the user entry using the PATCH method. +You've completed this tutorial. Next try other [tutorials](./tutorials.md) or refer to the [PUT](../reference/users/users-put.md) and [PATCH](../reference/users/users-patch.md) reference topics.