From 49bf0172150e94365326a6b8af35428dc6031f7c Mon Sep 17 00:00:00 2001
From: Taylor Steinberg <taylor.steinberg@posit.co>
Date: Tue, 26 Mar 2024 10:59:56 -0400
Subject: [PATCH] docs: updates readme with additional usage information (#131)

---
 README.md                  | 29 +++++++++++++++++++----
 examples/0001-overview.qmd | 47 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 72 insertions(+), 4 deletions(-)
 create mode 100644 examples/0001-overview.qmd

diff --git a/README.md b/README.md
index 5e529974..1833498e 100644
--- a/README.md
+++ b/README.md
@@ -12,15 +12,36 @@ pip install posit-sdk
 
 ## Usage
 
+Establish server information and credentials using the following environment variables or when initializing a client. Then checkout some [examples](./examples/0001-overview.qmd) to get started.
+
+> [!CAUTION]
+> It is important to keep your API key safe and secure. Your API key grants access to your account and allows you to make authenticated requests to the Posit API. Treat your API key like a password and avoid sharing it with others. If you suspect that your API key has been compromised, regenerate a new one immediately to maintain the security of your account.
+
+### Option 1 (Preferred)
+
+```shell
+export CONNECT_API_KEY="my-secret-api-key"
+export CONNECT_SERVER="https://example.com/"
+```
+
+```python
+from posit.connect import Client
+
+with Client() as client:
+    print(client)
+```
+
+### Option 2
+
 ```python
 from posit.connect import Client
 
-# If CONNECT_API_KEY and CONNECT_SERVER are set in your environment,
-# they will be picked up, or you can pass them as arguments
-con = Client()
-con.users.find()
+with Client(api_key="my-secret-api-key", url="https://example.com") as client:
+    print(client)
 ```
 
+
+
 ## Contributing
 
 We welcome contributions to the Posit SDK for Python! If you would like to contribute, see the [CONTRIBUTING](CONTRIBUTING.md) guide for instructions.
diff --git a/examples/0001-overview.qmd b/examples/0001-overview.qmd
new file mode 100644
index 00000000..a870bb17
--- /dev/null
+++ b/examples/0001-overview.qmd
@@ -0,0 +1,47 @@
+# Overview
+
+This file provides a collection of short examples to help users get started.
+
+The examples cover various aspects, including authentication, data retrieval, and data manipulation.
+
+## Example - Print information for each user where `user_role='publisher'`
+
+```python
+from posit.connect import Client
+
+with Client() as client:
+    for user in client.users.find(user_role='publisher'):
+        print(user)
+```
+
+## Example - Print information for a single user where `prefix='b'`
+
+```python
+from posit.connect import Client
+
+with Client() as client:
+    user = client.users.find_one(prefix='b')
+    print(user)
+```
+
+## Example - Print the title for each content item that I own.
+
+```python
+from posit.connect import Client
+
+with Client() as client:
+    guid = client.me.guid
+    for item in client.content.find(owner_guid=guid)
+        print(item.title)
+```
+
+## Example - Update the title for a content item.
+
+```python
+from posit.connect import Client
+
+with Client() as client:
+    guid = ... # the guid for a content item
+    item = client.content.get(guid)
+    item.update(title='New Title')
+```