[ISSUE] missing documentation for `permissions` API

[imarkowitz]

Description

There's no documentation here: https://github.com/databricks/databricks-sdk-py/blob/2b952c9960b2d22c9ae6e52ca7de09300ecac9cb/databricks/sdk/service/iam.py#L2203

instead it just says <needs content>.

This API really needs documentation. What is a request_object_type and what are possible values here?

I'm trying to update permissions for a python wheel and I have no idea what the type string should be.

[hectorcast-db]

Hi @imarkowitz Thanks for reaching out. We will improve the documentations for this object. However, most likely you are looking for a different object. This is the generic permissions class, but there are classes and methods dedicated to handle permissions for each Databricks resource. For instance, here the objects and methods to get the permissions for a Job https://github.com/databricks/databricks-sdk-py/blob/3a8b042436629ec844f1229e4e5f3f5497ce6728/databricks/sdk/service/jobs.py#L4827

[imarkowitz]

Thanks, I think it would be helpful to add that information to the documentation as well.

Documentation on those APIs seems inadequate as well. For example, https://github.com/databricks/databricks-sdk-py/blob/3a8b042436629ec844f1229e4e5f3f5497ce6728/databricks/sdk/service/workspace.py#L2178 -- what are valid possible values for "workspace_object_type" here?

Thanks