Allow for same param name but different contextual usage

[gjtorikian]

Description

As #519 notes, #512 corrected one problem and introduced another.

The param provided by users through the SDK is user_id/ group_id / directory_id; the API accepts parameters as user / group / directory by the API, without the suffix. What I misunderstood was that pagination actually requires the *_id version of these parameters, so while #512 fixed pagination (by using *_id), it went ahead and broke regular API calls (by using the incorrect, suffixless parameters).

Makes sense? Yeah, I had to re-read everything a few times myself to understand the difference in usage. The key is in these lines (repeated throughout several API resources, I'm just picking one):

  response = self._http_client.request(
            "directory_users",
            method=REQUEST_METHOD_GET,
            params=list_params,
        )

        return WorkOSListResource(
            list_method=self.list_users,
            list_args=list_params,
            **ListPage[DirectoryUserWithGroups](**response).model_dump(),
        )

The request uses list_params, and then the pagination WorkOSListResource uses list_params again.

To solve this, I added a function to translate the parameter name, depending on the context it's used. Essentially, this branch keeps the *_id names internally for pagination, then renames to the suffixless version them right before the HTTP call.

Documentation

Does this require changes to the WorkOS Docs? E.g. the API Reference or code snippets need updates.

[ ] Yes

If yes, link a related docs PR and add a docs maintainer as a reviewer. Their approval is required.

[greptile-apps]

Greptile Summary

This PR fixes a parameter naming mismatch between the SDK and API by introducing a translation layer at the HTTP request boundary. The SDK uses Pythonic parameter names (directory_id, group_id, user_id) which are preserved internally for pagination, but the WorkOS API expects shorter names (directory, group, user). The new _prepare_request_params() function translates parameter names only when making HTTP requests, ensuring both API calls and pagination work correctly.

• Added _prepare_request_params() helper function with clear parameter mapping
• Applied translation in all four list methods (list_users and list_groups for both sync and async classes)
• Updated existing tests to verify translated parameters are sent to API
• Added comprehensive test suite for the translation function covering all parameter types and edge cases

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The solution is well-architected, correctly addresses the dual-context parameter naming issue, and includes comprehensive test coverage. The translation function is simple, clear, and applied consistently across all affected methods. Only minor style issue with import ordering.
• No files require special attention

Important Files Changed

Filename	Overview
src/workos/directory_sync.py	Adds _prepare_request_params() function to translate SDK parameter names (*_id) to API parameter names (without suffix) at HTTP request boundary; applies translation in all four list methods
tests/test_directory_sync.py	Updates existing tests to expect translated parameter names in HTTP requests; adds comprehensive test suite for _prepare_request_params() function; has unusual import ordering (split imports from same module)

Sequence Diagram

sequenceDiagram
    participant User
    participant DirectorySync
    participant PrepareParams as _prepare_request_params()
    participant HTTPClient
    participant WorkOSAPI as WorkOS API
    participant ListResource as WorkOSListResource

    User->>DirectorySync: list_users(directory_id="dir_123")
    DirectorySync->>DirectorySync: Create list_params with directory_id
    DirectorySync->>PrepareParams: _prepare_request_params(list_params)
    PrepareParams->>PrepareParams: Translate directory_id → directory
    PrepareParams-->>DirectorySync: request_params with "directory"
    DirectorySync->>HTTPClient: request(params=request_params)
    HTTPClient->>WorkOSAPI: GET /directory_users?directory=dir_123
    WorkOSAPI-->>HTTPClient: Response with users
    HTTPClient-->>DirectorySync: response
    DirectorySync->>ListResource: Create WorkOSListResource(list_args=list_params)
    Note over ListResource: list_args contains directory_id for pagination
    
    User->>ListResource: Iterate (pagination)
    ListResource->>DirectorySync: list_users(directory_id="dir_123", after="cursor")
    DirectorySync->>PrepareParams: _prepare_request_params(list_params)
    PrepareParams-->>DirectorySync: request_params with "directory"
    DirectorySync->>HTTPClient: request(params=request_params)
    HTTPClient->>WorkOSAPI: GET /directory_users?directory=dir_123&after=cursor
    WorkOSAPI-->>HTTPClient: Next page
    HTTPClient-->>ListResource: response

Loading

[greptile-apps]

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}