From 839fd7ebca9685c5aca47eb428024179d0857243 Mon Sep 17 00:00:00 2001
From: Sean Starkey <sean@seanstarkey.com>
Date: Tue, 2 Jun 2026 09:12:04 -0600
Subject: [PATCH] Add API Usage

---
 README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/README.md b/README.md
index e33633c..ab4e067 100644
--- a/README.md
+++ b/README.md
@@ -78,6 +78,75 @@ A React app located at https://git.seanstarkey.dev/starkey/notes was used to tes
 | `DELETE` | `/notes/{id}`      | Delete a note (owner only) |
 | `POST`   | `/notes/{id}/share` | Share a note with another user (read-only) |
 
+## API Usage Examples
+
+The following examples assume the API is running at `http://localhost:8080`.
+
+Register two users:
+
+```bash
+curl -i -X POST http://localhost:8080/auth/register \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"alice","password":"password123"}'
+
+curl -i -X POST http://localhost:8080/auth/register \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"bob","password":"password123"}'
+```
+
+Log in and save each JWT:
+
+```bash
+ALICE_TOKEN=$(curl -s -X POST http://localhost:8080/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"alice","password":"password123"}' | jq -r '.token')
+
+BOB_TOKEN=$(curl -s -X POST http://localhost:8080/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"bob","password":"password123"}' | jq -r '.token')
+```
+
+Create a note as Alice:
+
+```bash
+NOTE_ID=$(curl -s -X POST http://localhost:8080/notes \
+  -H "Authorization: Bearer $ALICE_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"title":"Launch checklist","content":"Rotate credentials before launch."}' | jq -r '.id')
+```
+
+List Alice's visible notes:
+
+```bash
+curl -i http://localhost:8080/notes \
+  -H "Authorization: Bearer $ALICE_TOKEN"
+```
+
+Share Alice's note with Bob:
+
+```bash
+curl -i -X POST http://localhost:8080/notes/$NOTE_ID/share \
+  -H "Authorization: Bearer $ALICE_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"bob"}'
+```
+
+Bob can read the shared note:
+
+```bash
+curl -i http://localhost:8080/notes/$NOTE_ID \
+  -H "Authorization: Bearer $BOB_TOKEN"
+```
+
+Bob cannot update the shared note because shared access is read-only:
+
+```bash
+curl -i -X PUT http://localhost:8080/notes/$NOTE_ID \
+  -H "Authorization: Bearer $BOB_TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"title":"Edited by Bob","content":"This update should be rejected."}'
+```
+
 ## HTTP return codes
 
 Application-defined HTTP status codes are generated in `AuthController` for successful registration and in `GlobalExceptionHandler` for API error responses. Spring Security and Spring MVC may still produce framework-level responses for requests that do not reach a controller, such as unauthenticated protected requests or unsupported methods.