From 8f63900438c1a4037836b397bc68e1a547778d58 Mon Sep 17 00:00:00 2001 From: Daniel Perrefort Date: Tue, 9 Dec 2025 20:45:51 -0500 Subject: [PATCH 1/6] Breaks up documentation across multiple pages --- docs/index.md | 315 +---------------------------------------------- docs/logging.md | 28 +++++ docs/requests.md | 171 +++++++++++++++++++++++++ docs/session.md | 99 +++++++++++++++ mkdocs.yml | 5 + 5 files changed, 308 insertions(+), 310 deletions(-) create mode 100644 docs/logging.md create mode 100644 docs/requests.md create mode 100644 docs/session.md diff --git a/docs/index.md b/docs/index.md index f0a3987..614293b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,322 +1,17 @@ ---- -hide: - - navigation ---- - # Introduction Keystone provides a Python client for streamlining interactions with the application's REST API. -The client automates user authentication and data parsing, freeing developers to focus on core application logic. - -## Installation +The client automates user authentication and data parsing, freeing developers to focus on their core application logic. The Python client is hosted on PyPI and can be installed in the standard fashion. +```bash +pip install keystone-api-client +``` + !!! note "Version Compatibility" The API client version should match the major and minor version of the upstream API server. For example, if the API version is `2.3.x`, the compatible client version is `2.3.y`. Using a mismatched client version may still function, but compatibility is not guaranteed and may result in inconsistent behavior. - - -```bash -pip install keystone-api-client -``` - -## Instantiating a Client - -The client package provides support for synchronous and asynchronous API calls. -In both cases, requests are pooled across a shared session, reducing HTTP overhead. -The following example instantiates a new session for a locally running server on port `8000`. -Creating the session with a context manager ensures open connections are automatically closed when no longer in use. - -=== "Synchronous" - - ```python - from keystone_client import KeystoneClient - - with KeystoneClient(url="http://localhost:8000") as client: - ... # Your synchronous code here - ``` - -=== "Asynchronous" - - ```python - from keystone_client import AsyncKeystoneClient - - async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: - ... # Your asynchronous code here - ``` - -Sessions can also be opened and closed manually. -This approach is generally discouraged as it increases the likelihood of resource leaks and unclosed connections. - -=== "Synchronous" - - ```python - from keystone_client import KeystoneClient - - client = KeystoneClient(url="http://localhost:8000"): - # Your synchronous code here - client.close() - ``` - -=== "Asynchronous" - - ```python - from keystone_client import AsyncKeystoneClient - - aclient = AsyncKeystoneClient(url="http://localhost:8000"): - # Your asynchronous code here - await aclient.close() - ``` - -Client sessions will automatically manage any relevant session tokens. -This includes assigning a unique correlation ID (CID) used to track requests across Keystone application logs. -CID values are suitable for inclusion in log messages, passing to downstream services, or correlating requests -for debugging and performance monitoring. - -=== "Synchronous" - - ```python - from keystone_client import KeystoneClient - - with KeystoneClient(url="http://localhost:8000") as client: - print(client.cid) - ``` - -=== "Asynchronous" - - ```python - from keystone_client import AsyncKeystoneClient - - async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: - print(aclient.cid) - ``` - -## Authenticating a Session - -The `login` and `logout` methods are used to handle user authentication. -Once authenticated, the client will automatically manage the resulting session tokens. - -=== "Synchronous" - - ```python - from keystone_client import KeystoneClient - - with KeystoneClient(url="http://localhost:8000") as client: - client.login(username="username", password="password") - assert client.is_authenticated() - client.logout() - ``` - -=== "Asynchronous" - - ```python - from keystone_client import AsyncKeystoneClient - - async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: - await aclient.login(username="username", password="password") - assert await aclient.is_authenticated() - await aclient.logout() - ``` - -## Generic HTTP Requests - -Client classes provide dedicated methods for each HTTP request type supported by the API. -Any relevant session/authentication tokens are included automatically when submitting requests. - -| HTTP Method | Function Name | Description | -|-------------|---------------|----------------------------------------------------------| -| `GET` | `http_get` | Retrieve data from the server at the specified resource. | -| `POST` | `http_post` | Submit a new record to be processed by the server. | -| `PUT` | `http_put` | Replace an existing record with a new one. | -| `PATCH` | `http_patch` | Partially update an existing record. | -| `DELETE` | `http_delete` | Remove the specified record from the server. | - -Request/response logic is handled using the `httpx` library. -API responses are returned as `httpx.Response` objects which encapsulate the response data and status code. -Users are encouraged to familiarize themselves with the `httpx.Response` object and it's methods for parsing response -data and related metadata. -A simple example is provided below. - -=== "Synchronous" - - ```python - from keystone_client import KeystoneClient - - with KeystoneClient(url="http://localhost:8000") as client: - response = client.http_get('version') - - response.raise_for_status() - print(response.status_code) - print(response.content) - ``` - -=== "Asynchronous" - - ```python - from keystone_client import AsyncKeystoneClient - - async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: - response = await aclient.http_get('version') - - response.raise_for_status() - print(response.status_code) - print(response.content) - ``` - -## CRUD Operations - -Dedicated methods are provided for create, retrieve, update, and delete (CRUD) operations for each API resource. -These methods simplify data manipulation by automatically handling the request and response logic. - -CRUD methods adhere to the following naming scheme: - -| Method Name | Description | -|-----------------------|----------------------------------------------------------| -| `create_{resource}` | Create a new record for the specified resource. | -| `retrieve_{resource}` | Retrieve one or more records for the specified resource. | -| `update_{resource}` | Update an existing record for the specified resource. | -| `delete_{resource}` | Delete an existing record for the specified resource. | - -### Creating Records - -Create methods are used to submit new records to the API server. -These methods accept record details as keyword arguments and return a dictionary with the successfully created record. - -=== "Synchronous" - - ```python - new_record_data = client.create_cluster( - name="New-Cluster", - description="Cluster created for example purposes." - ) - ``` - -=== "Asynchronous" - - ```python - new_record_data = await aclient.create_cluster( - name="New-Cluster", - description="Cluster created for example purposes." - ) - ``` - -### Retrieving Records - -Data retrieval methods are used to search and return existing records. -By default, these methods return all available records on the server as a list of dictionaries. -The `filters` argument can be used to optionally filter these values against a set of search parameters. -See the [filtering documentation](../../keystone-api/api/filtering/) for instructions on structuring search queries. - -=== "Synchronous" - - ```python - all_cluster_data = client.retrieve_cluster(filters={"name": "New-Cluster"}) - ``` - -=== "Asynchronous" - - ```python - all_cluster_data = await aclient.retrieve_cluster(filters={"name": "New-Cluster"}) - ``` - -In situations where a record's primary key (i.e., it's `id` field) is already known, the individual record can be -retrieved directly. - -=== "Synchronous" - - ```python - single_cluster_data = client.retrieve_cluster(pk=1) - ``` - -=== "Asynchronous" - - ```python - single_cluster_data = await aclient.retrieve_cluster(pk=1) - ``` - -### Updating Records - -Update operations are used to modify values for an existing record. -Doing so requires specifying the record's primary key in addition to the new record values. - -=== "Synchronous" - - ```python - updated_record_data = client.update_cluster( - pk=1, - data={'description': "Updated description"} - ) - ``` - -=== "Asynchronous" - - ```python - updated_record_data = await aclient.update_cluster( - pk=1, - data={'description': "Updated description"} - ) - ``` - -### Deleting Records - -Delete methods are used to remove records from the server. - -=== "Synchronous" - - ```python - client.delete_cluster(pk=1) - ``` - -=== "Asynchronous" - - ```python - await aclient.delete_cluster(pk=1) - ``` - -If a record does not exist for the provided primary key, the function call will exit silently. -The `raise_not_exists` argument can be used to raise an exception instead. - -=== "Synchronous" - - ```python - client.delete_cluster(pk=1, raise_not_exists=True) - ``` - -=== "Asynchronous" - - ```python - await aclient.delete_cluster(pk=1, raise_not_exists=True) - ``` - -## Application Logging - -API clients automatically log all requests to the `kclient` log handler. -In addition to the standard default values, `kclient` logs include the application specific values listed below. - -| Field Name | Description | -|------------|----------------------------------------------------------------------------| -| `cid` | Per-session logging id used to correlate requests across a client session. | -| `baseurl` | Base API server URL, including http protocol. | -| `method` | HTTP method for outgoing requests, or an empty string if not applicable. | -| `endpoint` | API endpoint for outgoing requestst, or an empty string if not applicable. | -| `url` | Full API URL for outgoing requests, or an empty string if not applicable. | - -The `kclient` logger is automatically registered when importing the `keystone_client` package. -Formatting, filtering, and persisting log values is left to the user. -For example: - -```python -import logging -import keystone_client - -handler = logging.StreamHandler() -handler.setFormatter( - logging.Formatter('%(cid)s - %(baseurl)s - %(method)s - %(endpoint)s - %(message)s') -) - -logging.getLogger('kclient').addHandler(handler) -``` diff --git a/docs/logging.md b/docs/logging.md new file mode 100644 index 0000000..9be6a68 --- /dev/null +++ b/docs/logging.md @@ -0,0 +1,28 @@ +# Application Logging + +API clients automatically log all requests to the `kclient` log handler. +In addition to the standard default values, `kclient` logs include the application specific values listed below. + +| Field Name | Description | +|------------|----------------------------------------------------------------------------| +| `cid` | Per-session logging id used to correlate requests across a client session. | +| `baseurl` | Base API server URL, including http protocol. | +| `method` | HTTP method for outgoing requests, or an empty string if not applicable. | +| `endpoint` | API endpoint for outgoing requestst, or an empty string if not applicable. | +| `url` | Full API URL for outgoing requests, or an empty string if not applicable. | + +The `kclient` logger is automatically registered when importing the `keystone_client` package. +Formatting, filtering, and persisting log values is left to the user. +For example: + +```python +import logging +import keystone_client + +handler = logging.StreamHandler() +handler.setFormatter( + logging.Formatter('%(cid)s - %(baseurl)s - %(method)s - %(endpoint)s - %(message)s') +) + +logging.getLogger('kclient').addHandler(handler) +``` diff --git a/docs/requests.md b/docs/requests.md new file mode 100644 index 0000000..433fab9 --- /dev/null +++ b/docs/requests.md @@ -0,0 +1,171 @@ +# Making API Requests + +## Generic HTTP Requests + +Client classes provide dedicated methods for each HTTP request type supported by the API. +Any relevant session/authentication tokens are included automatically when submitting requests. + +| HTTP Method | Function Name | Description | +|-------------|---------------|----------------------------------------------------------| +| `GET` | `http_get` | Retrieve data from the server at the specified resource. | +| `POST` | `http_post` | Submit a new record to be processed by the server. | +| `PUT` | `http_put` | Replace an existing record with a new one. | +| `PATCH` | `http_patch` | Partially update an existing record. | +| `DELETE` | `http_delete` | Remove the specified record from the server. | + +Request/response logic is handled using the `httpx` library. +API responses are returned as `httpx.Response` objects which encapsulate the response data and status code. +Users are encouraged to familiarize themselves with the `httpx.Response` object and it's methods for parsing response +data and related metadata. +A simple example is provided below. + +=== "Synchronous" + + ```python + from keystone_client import KeystoneClient + + with KeystoneClient(url="http://localhost:8000") as client: + response = client.http_get('version') + + response.raise_for_status() + print(response.status_code) + print(response.content) + ``` + +=== "Asynchronous" + + ```python + from keystone_client import AsyncKeystoneClient + + async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: + response = await aclient.http_get('version') + + response.raise_for_status() + print(response.status_code) + print(response.content) + ``` + +## CRUD Operations + +Dedicated methods are provided for create, retrieve, update, and delete (CRUD) operations for each API resource. +These methods simplify data manipulation by automatically handling the request and response logic. + +CRUD methods adhere to the following naming scheme: + +| Method Name | Description | +|-----------------------|----------------------------------------------------------| +| `create_{resource}` | Create a new record for the specified resource. | +| `retrieve_{resource}` | Retrieve one or more records for the specified resource. | +| `update_{resource}` | Update an existing record for the specified resource. | +| `delete_{resource}` | Delete an existing record for the specified resource. | + +### Creating Records + +Create methods are used to submit new records to the API server. +These methods accept record details as keyword arguments and return a dictionary with the successfully created record. + +=== "Synchronous" + + ```python + new_record_data = client.create_cluster( + name="New-Cluster", + description="Cluster created for example purposes." + ) + ``` + +=== "Asynchronous" + + ```python + new_record_data = await aclient.create_cluster( + name="New-Cluster", + description="Cluster created for example purposes." + ) + ``` + +### Retrieving Records + +Data retrieval methods are used to search and return existing records. +By default, these methods return all available records on the server as a list of dictionaries. +The `filters` argument can be used to optionally filter these values against a set of search parameters. +See the [filtering documentation](../../keystone-api/api/filtering/) for instructions on structuring search queries. + +=== "Synchronous" + + ```python + all_cluster_data = client.retrieve_cluster(filters={"name": "New-Cluster"}) + ``` + +=== "Asynchronous" + + ```python + all_cluster_data = await aclient.retrieve_cluster(filters={"name": "New-Cluster"}) + ``` + +In situations where a record's primary key (i.e., it's `id` field) is already known, the individual record can be +retrieved directly. + +=== "Synchronous" + + ```python + single_cluster_data = client.retrieve_cluster(pk=1) + ``` + +=== "Asynchronous" + + ```python + single_cluster_data = await aclient.retrieve_cluster(pk=1) + ``` + +### Updating Records + +Update operations are used to modify values for an existing record. +Doing so requires specifying the record's primary key in addition to the new record values. + +=== "Synchronous" + + ```python + updated_record_data = client.update_cluster( + pk=1, + data={'description': "Updated description"} + ) + ``` + +=== "Asynchronous" + + ```python + updated_record_data = await aclient.update_cluster( + pk=1, + data={'description': "Updated description"} + ) + ``` + +### Deleting Records + +Delete methods are used to remove records from the server. + +=== "Synchronous" + + ```python + client.delete_cluster(pk=1) + ``` + +=== "Asynchronous" + + ```python + await aclient.delete_cluster(pk=1) + ``` + +If a record does not exist for the provided primary key, the function call will exit silently. +The `raise_not_exists` argument can be used to raise an exception instead. + +=== "Synchronous" + + ```python + client.delete_cluster(pk=1, raise_not_exists=True) + ``` + +=== "Asynchronous" + + ```python + await aclient.delete_cluster(pk=1, raise_not_exists=True) + ``` diff --git a/docs/session.md b/docs/session.md new file mode 100644 index 0000000..bffb1aa --- /dev/null +++ b/docs/session.md @@ -0,0 +1,99 @@ +# Starting a Session + +## Instantiating a Client + +The client package provides support for synchronous and asynchronous API calls. +In both cases, requests are pooled across a shared session, reducing HTTP overhead. +The following example instantiates a new session for a locally running server on port `8000`. +Creating the session with a context manager ensures open connections are automatically closed when no longer in use. + +=== "Synchronous" + + ```python + from keystone_client import KeystoneClient + + with KeystoneClient(url="http://localhost:8000") as client: + ... # Your synchronous code here + ``` + +=== "Asynchronous" + + ```python + from keystone_client import AsyncKeystoneClient + + async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: + ... # Your asynchronous code here + ``` + +Sessions can also be opened and closed manually, although this approach is generally discouraged as it increases +the likelihood of resource leaks and unclosed connections. + +=== "Synchronous" + + ```python + from keystone_client import KeystoneClient + + client = KeystoneClient(url="http://localhost:8000"): + # Your synchronous code here + client.close() + ``` + +=== "Asynchronous" + + ```python + from keystone_client import AsyncKeystoneClient + + aclient = AsyncKeystoneClient(url="http://localhost:8000"): + # Your asynchronous code here + await aclient.close() + ``` + +Client sessions will automatically manage any relevant session tokens. +This includes assigning a unique correlation ID (CID) used to track requests across Keystone application logs. +CID values are suitable for inclusion in log messages, passing to downstream services, or correlating requests +for debugging and performance monitoring. + +=== "Synchronous" + + ```python + from keystone_client import KeystoneClient + + with KeystoneClient(url="http://localhost:8000") as client: + print(client.cid) + ``` + +=== "Asynchronous" + + ```python + from keystone_client import AsyncKeystoneClient + + async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: + print(aclient.cid) + ``` + +## Authenticating a Session + +The `login` and `logout` methods are used to handle user authentication. +Once authenticated, the client will automatically manage the resulting session tokens. + +=== "Synchronous" + + ```python + from keystone_client import KeystoneClient + + with KeystoneClient(url="http://localhost:8000") as client: + client.login(username="username", password="password") + assert client.is_authenticated() + client.logout() + ``` + +=== "Asynchronous" + + ```python + from keystone_client import AsyncKeystoneClient + + async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: + await aclient.login(username="username", password="password") + assert await aclient.is_authenticated() + await aclient.logout() + ``` diff --git a/mkdocs.yml b/mkdocs.yml index eee1068..d5b4d26 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1 +1,6 @@ site_name: Keystone Python Client +nav: + - index.md + - session.md + - requests.md + - logging.md From da92bd3ea521edc1394ea049ccaa6f557f662da5 Mon Sep 17 00:00:00 2001 From: Daniel Perrefort Date: Wed, 10 Dec 2025 09:43:58 -0500 Subject: [PATCH 2/6] Rewrite introduction page --- docs/{index.md => installation.md} | 9 +++++---- mkdocs.yml | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) rename docs/{index.md => installation.md} (52%) diff --git a/docs/index.md b/docs/installation.md similarity index 52% rename from docs/index.md rename to docs/installation.md index 614293b..7c773ee 100644 --- a/docs/index.md +++ b/docs/installation.md @@ -1,9 +1,10 @@ -# Introduction +# Install and Setup -Keystone provides a Python client for streamlining interactions with the application's REST API. -The client automates user authentication and data parsing, freeing developers to focus on their core application logic. +The Keystone platform includes an official Python client that simplifies integration with the application's REST API. +It handles authentication, request execution, and response parsing, allowing developers to concentrate on application +logic rather than API mechanics. -The Python client is hosted on PyPI and can be installed in the standard fashion. +The client is published on PyPI and can be installed in the standard fashion. ```bash pip install keystone-api-client diff --git a/mkdocs.yml b/mkdocs.yml index d5b4d26..272c401 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ site_name: Keystone Python Client nav: - - index.md + - installation.md - session.md - requests.md - logging.md From 81b147c98459b79b9e5f73a1d71d7232bc19cccb Mon Sep 17 00:00:00 2001 From: Daniel Perrefort Date: Wed, 10 Dec 2025 09:44:10 -0500 Subject: [PATCH 3/6] Rewrite logging page --- docs/logging.md | 56 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 43 insertions(+), 13 deletions(-) diff --git a/docs/logging.md b/docs/logging.md index 9be6a68..f4f6968 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -1,19 +1,14 @@ # Application Logging -API clients automatically log all requests to the `kclient` log handler. -In addition to the standard default values, `kclient` logs include the application specific values listed below. +The Keystone Python client exposes a dedicated logger (`kclient`) that records structured request metadata using the +standard Python logging framework. The logger is registered automatically when the package is imported and can be +configured like any other Python logger. -| Field Name | Description | -|------------|----------------------------------------------------------------------------| -| `cid` | Per-session logging id used to correlate requests across a client session. | -| `baseurl` | Base API server URL, including http protocol. | -| `method` | HTTP method for outgoing requests, or an empty string if not applicable. | -| `endpoint` | API endpoint for outgoing requestst, or an empty string if not applicable. | -| `url` | Full API URL for outgoing requests, or an empty string if not applicable. | +## Logger Configuration -The `kclient` logger is automatically registered when importing the `keystone_client` package. -Formatting, filtering, and persisting log values is left to the user. -For example: +Custom handlers, formatters, and filters may be attached directly to the kclient logger. +Because the logger behaves like any standard Python logger, you can control output destinations, define +message structures, adjust verbosity, and apply filtering based on logged metadata. ```python import logging @@ -21,8 +16,43 @@ import keystone_client handler = logging.StreamHandler() handler.setFormatter( - logging.Formatter('%(cid)s - %(baseurl)s - %(method)s - %(endpoint)s - %(message)s') + logging.Formatter('%(asctime)s %(levelname)s %(name)s: %(message)s') ) logging.getLogger('kclient').addHandler(handler) ``` + +In addition to the standard Python logging attributes, the `kclient` logger includes the following package-specific fields: + +| Field Name | Description | +|------------|----------------------------------------------------------------------------| +| `cid` | Per-session logging id used to correlate requests across a client session. | +| `baseurl` | Base API server URL, including http protocol. | +| `method` | HTTP method for outgoing requests, or an empty string if not applicable. | +| `endpoint` | API endpoint for outgoing requests, or an empty string if not applicable. | +| `url` | Full API URL for outgoing requests, or an empty string if not applicable. | + +## Session IDs + +Each client session is assigned a unique correlation ID (CID) that accompanies all emitted log records. +This identifier provides a reference value for correlating client and API logs across multiple endpoints and requests. +CID values are suitable for inclusion in log messages, passing to downstream services, or correlating requests +for debugging and performance monitoring. + +=== "Synchronous" + + ```python + from keystone_client import KeystoneClient + + with KeystoneClient(url="http://localhost:8000") as client: + print(client.cid) + ``` + +=== "Asynchronous" + + ```python + from keystone_client import AsyncKeystoneClient + + async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: + print(aclient.cid) + ``` From 8c19468337a46bd58c1937ea2c9ffdb9c3dc0d9f Mon Sep 17 00:00:00 2001 From: Daniel Perrefort Date: Wed, 10 Dec 2025 09:48:55 -0500 Subject: [PATCH 4/6] Rewrites session page --- docs/session.md | 28 ++++------------------------ 1 file changed, 4 insertions(+), 24 deletions(-) diff --git a/docs/session.md b/docs/session.md index bffb1aa..960b8ef 100644 --- a/docs/session.md +++ b/docs/session.md @@ -1,9 +1,12 @@ # Starting a Session +Interacting with the Keystone API begins by creating a client session. +Session objects encapsulate the connection state, authentication details, and request configuration, allowing the +client to efficiently reuse connections and manage resources across multiple API calls. + ## Instantiating a Client The client package provides support for synchronous and asynchronous API calls. -In both cases, requests are pooled across a shared session, reducing HTTP overhead. The following example instantiates a new session for a locally running server on port `8000`. Creating the session with a context manager ensures open connections are automatically closed when no longer in use. @@ -48,29 +51,6 @@ the likelihood of resource leaks and unclosed connections. await aclient.close() ``` -Client sessions will automatically manage any relevant session tokens. -This includes assigning a unique correlation ID (CID) used to track requests across Keystone application logs. -CID values are suitable for inclusion in log messages, passing to downstream services, or correlating requests -for debugging and performance monitoring. - -=== "Synchronous" - - ```python - from keystone_client import KeystoneClient - - with KeystoneClient(url="http://localhost:8000") as client: - print(client.cid) - ``` - -=== "Asynchronous" - - ```python - from keystone_client import AsyncKeystoneClient - - async with AsyncKeystoneClient(url="http://localhost:8000") as aclient: - print(aclient.cid) - ``` - ## Authenticating a Session The `login` and `logout` methods are used to handle user authentication. From 91a611a38980decb4035f4450f2edc17c8ac0b86 Mon Sep 17 00:00:00 2001 From: Daniel Perrefort Date: Wed, 10 Dec 2025 09:55:11 -0500 Subject: [PATCH 5/6] Rewrites requests page --- docs/requests.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/requests.md b/docs/requests.md index 433fab9..2db5ccb 100644 --- a/docs/requests.md +++ b/docs/requests.md @@ -1,5 +1,9 @@ # Making API Requests +Client classes (`KyestoneClient` and `AsyncKeystoneClient`) include a set of high-level interfaces for interacting the API. +These interfaces include generic HTTP methods for low-level access in addition to resource-specific CRUD helpers for common workflows. +All requests automatically include any active authentication or session metadata. + ## Generic HTTP Requests Client classes provide dedicated methods for each HTTP request type supported by the API. @@ -15,7 +19,7 @@ Any relevant session/authentication tokens are included automatically when submi Request/response logic is handled using the `httpx` library. API responses are returned as `httpx.Response` objects which encapsulate the response data and status code. -Users are encouraged to familiarize themselves with the `httpx.Response` object and it's methods for parsing response +Users are encouraged to familiarize themselves with the `httpx` library and it's methods for parsing response data and related metadata. A simple example is provided below. @@ -47,7 +51,7 @@ A simple example is provided below. ## CRUD Operations -Dedicated methods are provided for create, retrieve, update, and delete (CRUD) operations for each API resource. +Dedicated methods are provided for create, retrieve, update, and delete (CRUD) operations against each API resource. These methods simplify data manipulation by automatically handling the request and response logic. CRUD methods adhere to the following naming scheme: From 6cb042d20eeac3e0d806f97ce3a372701b4c8d57 Mon Sep 17 00:00:00 2001 From: Daniel Perrefort Date: Wed, 10 Dec 2025 09:59:38 -0500 Subject: [PATCH 6/6] Grammar edit --- docs/requests.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/requests.md b/docs/requests.md index 2db5ccb..9764a4c 100644 --- a/docs/requests.md +++ b/docs/requests.md @@ -1,7 +1,7 @@ # Making API Requests -Client classes (`KyestoneClient` and `AsyncKeystoneClient`) include a set of high-level interfaces for interacting the API. -These interfaces include generic HTTP methods for low-level access in addition to resource-specific CRUD helpers for common workflows. +Client classes (`KeystoneClient` and `AsyncKeystoneClient`) provide a high-level interface for interacting the API. +This includes methods for generic HTTP requests in addition to resource-specific CRUD helpers for common workflows. All requests automatically include any active authentication or session metadata. ## Generic HTTP Requests