[Feedback] Handling Jamf Pro Versioning in the SDK

まず JamfProClient と SessionConfig の初期化を追跡し、次に jamf-pro-version エンドポイントと Python の warnings モジュールをクライアントのライフサイクルにどのように組み込めるかを確認します。設定設計の確定、API メタデータモデル、最小バージョン・非推奨バージョン・最大バージョンに対する警告動作、および警告の取得方法に関するドキュメントが揃えば完了です。

During the JNUC presentation a question was raised about SDK compatibility with different versions of Jamf Pro as APIs are added, deprecated, and removed. This proposal outlines an approach to alerting developers to when they are using an API that may not be compatible with the version of Jamf Pro they've connected a client to, or if they are using an API that has been deprecated.

Current

Currently all API changes have to be referenced from release notes for each Jamf Pro version. The SDK does not include any mechanisms for alerting developers.

Proposed

The SDK should contain metadata about the API methods that have been added that track the version they were added (minimum), if they are deprecated (a true/false flag), and the version they were removed (maximum).

Client Jamf Pro Version

The SDK would need to know the version of Jamf Pro during client init. This could be provided statically, automatically retrieved from the Pro API jamf-pro-version endpoint, or ignored.

As a part of this proposal the default behavior on client init would include an authenticated call to GET jamf-pro-version. This behavior may not be desirable as it requires authentication which means the client is making two network calls immediately.

Passing the version string on init would bypass this. Choosing to ignore the client version through an argument would then disable ALL of the warning system.

This new option should be added to the client config.

from jamf_pro_sdk import JamfProClient, BasicAuthProvider, SessionConfig

config = SessionConfig()
config.server_version = "10.50"
client.server_version = None  # <-- Default, triggers call to jamf-pro-version API
client.ignore_server_version = True  # <-- Default is False, setting True will disable all Jamf Pro version warnings

client = JamfProClient(
    server="jamf.my.org",
    credentials=BasicAuthProvider("oscar", "j@mf1234!"),
    config=config
)

API Warnings

If the client is instantiated with a version then all endpoints would need to emit WARNINGS when a method is being used that:

1. Has a minimum version ABOVE the client's Jamf Pro version.
2. Has been flagged as deprecated and should be migrated off of.
3. Has a maximum version LOWER than the client's Jamf Pro version.

This will be handled using Python's warnings module. Each unique warning will only appear once. The loggers can be configured to capture warning messages so developers will know when a particular client is making requests that meet one of the conditions above.

import logging
import warnings

from jamf_pro_sdk import logger_quick_setup

logger_quick_setup()  # Updated to include capturing warnings 
# logging.captureWarnings(True)
# warnings_logger = logging.getLogger("py.warnings")
# warnings_logger.addHandler(handler)

warnings.warn("This API is deprecated as of version 10.50 and will be removed in a future.")
# 2023-10-05 10:30:04,746 py.warnings WARNING MainThread <stdin>:1: UserWarning: This API is deprecated as of Jamf Pro 10.50 and will be removed in a future version.

When a deprecation flag is set there should be included a message for which API method the developer should migrate to using (if one exists). This migration message should carry forward for case 3.

The SDK will NOT throw version exceptions as a part of this warnings system. The client will return 404 errors if the API does not exist and the warning message can be captured in logs if the developer follows guidance in the documentation.