microsoft / microsoft/kiota

Handling of optional function parameters

Open
#2,584 5 comments 0 reactions 0 assignees View on GitHub
blocked enhancement generator needs more information type:bug
Dominant language
C#
Stars
3.8k
Forks
333
Avg merge
16h 29m
Merged PRs (30d)
116

Description

Related to
- https://github.com/microsoft/OpenAPI.NET.OData/issues/259
- https://github.com/microsoft/OpenAPI.NET.OData/pull/195
- https://github.com/microsoft/OpenAPI.NET.OData/pull/272

According to the conversion library changes above, if a function has optional parameters, the parameter will be marked to be
`in: query` rather than `in: path`

example.

```yaml
/roleManagement/entitlementManagement/roleDefinitions/{unifiedRoleDefinition-id}/inheritsPermissionsFrom/{unifiedRoleDefinition-id1}/assignedPrincipals(transitive=@transitive,directoryScopeType=''@directoryScopeType'',directoryScopeId=''@directoryScopeId'')':
description: Provides operations to call the assignedPrincipals method.
get:
tags:
- roleManagement.Functions
summary: Invoke function assignedPrincipals
operationId: roleManagement.entitlementManagement.roleDefinitions.unifiedRoleDefinition.inheritsPermissionsFrom.unifiedRoleDefinition.assignedPrincipals
parameters:
- name: transitive
in: query
description: 'Usage: transitive=@transitive'
schema:
type: boolean
default: false
- name: directoryScopeType
in: query
description: 'Usage: directoryScopeType=''@directoryScopeType'''
schema:
type: string
- name: directoryScopeId
in: query
description: 'Usage: directoryScopeId=''@directoryScopeId'''
schema:
type: string
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/count'
- name: $select
in: query
description: Select properties to be returned
style: form
explode: false
schema:
uniqueItems: true
type: array
items:
enum:
- id
- deletedDateTime
type: string
```

Kiota however interprets this as a query parameter and adds query options to
- the URL template e.g. `/roleDefinitions/{unifiedRoleDefinition%2Did}/assignedPrincipals(transitive=@transitive,directoryScopeType='@directoryScopeType',directoryScopeId='@directoryScopeId'){?transitive*,directoryScopeType*,directoryScopeId*,%24top,%24skip,%24search,%24filter,%24count,%24select,%24orderby}`
- QueryParameter object e.g https://github.com/microsoftgraph/msgraph-beta-sdk-dotnet/blob/56ec7408c228ee8d1eb58add9510c21a96c0aeea/src/Microsoft.Graph/Generated/RoleManagement/CloudPC/RoleDefinitions/Item/AssignedPrincipalsWithTransitivedirectoryScopeTypeDirectoryScopeTypeDirectoryScopeIdDirectoryScopeId/AssignedPrincipalsWithTransitivedirectoryScopeTypeDirectoryScopeTypeDirectoryScopeIdDirectoryScopeIdRequestBuilder.cs#L77

As this is a function, this brings up a few points/queries.
- As the function has optional parameters. It would make sense to have overloads generated (depending on the language) with the parameters passed.
- Trying to call the function with (no parameter passed) would result in an invalid url as the template would resolve to calling the function with placeholders instead of them being omitted from the url completely. The url template generation needs to cater for this.
- If passing the optional parameters through the query parameters object works, this is not intuitive as the function segment in the SDK is generated without parameters and the experience would involve using the query parameter object. At the moment, the url template generation now would add the parameters to the query parameters as well.

If having optional parameters in the query is an Odata specific conversion issue and is not expected in `any` OpenAPI description that Kiota would consume, we may have to move this conversation to the conversion library.

cc @baywet @darrelmiller

Contributor guide

Open the contributing guide

Research direction

Start with Kiota's URL-template generation and query-parameter handling, using the generated AssignedPrincipals...RequestBuilder.cs link in the issue as the concrete example. Determine how optional function parameters should be represented when omitted or supplied, and verify that generated URLs do not retain placeholders or duplicate parameters; no test file is named in the issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, openapi
Domain
api, tooling
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.