microsoft / microsoft/typespec
Revisit @parameterVisibility and @returnVisibility
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
I'm struggling to understand the new `@parameterVisibility` and `@returnVisibility` decorators.
I know that these were introduced to address azure/typespec-azure#3214 (patch operation should define "create" properties in request body). I think the root of that issue is that the http library assumes "patch" is "update" and there was no way to mark a "patch" to say "this is both create and update".
Stepping back, here's what the core docs say about `@visibility`:
> the following visibilities are well-known to standard libraries and should be used with standard emitters that interpret them as follows:
> - "read": output of any operation.
> - "create": input to operations that create an entity.
> - "query": input to operations that read data.
> - "update": input to operations that update data.
> - "delete": input to operations that delete data.
This combined with the documentation of [Automatic visibility in the HTTP library](https://microsoft.github.io/typespec/standard-library/http/operations#automatic-visibility) implies
- GET and HEAD requests "read data" -- because "query" visibility is automatically applied.
- POST and PUT requests "create an entity" -- because "create" visibility is automatically applied.
- PATCH and PUT requests "update data" -- because "update" visibility is automatically applied.
- DELETE requests "delete data" -- because "update" visibility is automatically applied.
But the HTTP library provides no means to deviate from this. I think what is missing is the ability to characterize an operation deviates from the above assumptions. PATCH that is "createOrUpdate" is a great example, but another common one is POST that does not "create an entity".
A decorator implemented in the HTTP library (could also be in core I suppose), say `@operationType` that could specify some combination of "create", "query", "update", or "delete" could fill this gap. The a PATCH operation that allows "create" or "update" could be defined with
```
@operationType("create", "update")
@patch op createOrUpdate(...Widget): Widget | Error;
```
and the HTTP library or downstream emitter could then "do the right thing".
Contributor guide
Assessment
This issue has not been assessed yet.