-
Notifications
You must be signed in to change notification settings - Fork 214
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Support for explicit HTTP parts #3046
Comments
@timotheeguerin One more ask... But I was wondering if we plan to accept this requirement in typespec side. Some service may want the default value for filename, some may not. Is it possible to allow service team to define this? maybe define in client-level setting or property-level one? Also I notice that when the filename is optional, whether to set default value may be inconsistant cross language, so what is the final decision? @timovv any insight? |
I don't think this was part of this design, this only covers the fact that you can make the filename a required property in a part.(You can also set a default with a property default but that would be the service default) For client we don't have any defaults yet so feels like that design needs to be sorted out first. |
resolve #3046 [Playground](https://cadlplayground.z22.web.core.windows.net/prs/3342/) Add the following: - `@multipartBody` decorator - `File` type - `HttpPart<Type, Options>` type Had to do a decent amount of refactoring to be able to reuse the body parsing, this result in a much cleaner resolution of the body and other metadata properties across request, response and metadata. The way it works now is instead of calling `gatherMetadata` that would just get the properties that are metadata but also ones with `@body` and `@bodyRoot` we now call a `resolveHtpProperties`, this does the same resolution in term of filtering properties but it also figure out what is the kind of property in the concept of http(header, query, body, etc.) this leaves the error resolution to this function for duplicate annotations. What is nice is now we don't need to keep asking oh is this a query or a header or a body we can just check the kind of `HttpProperty` also resolve #1311
We have made some initial forays into multipart/form-data by piggy-backing off of the OpenAPI approach, which essentially maps a JSON-like structure to parts through various rules, like the object keys are the form name, "bytes" means "files", arrays mean multiple parts, etc. This works well for simple cases, but leaves behind some gaps, and has some non-optimal behavior. In particular:
explode
,deepObject
, etc.Overall, while the current design of making MFD endpoints "feel like" they take an object, and emitters doing the best they can to represent an endpoint that takes that object across multiple parts, this leaves a lot of gaps.
OpenAPI addresses these limitations with the
encoding
property that lives alongside schema:multipart/form-data
is a more specialized form of multipart requests. OpenAPI has support formultipart/mixed
, and uses the same definition for it (NB: it is not clear whether the schema properties are reflected in a multipart/mixed request in the same way they are for multipart/form-data using the content disposition header, but this would be strange given that multipart/mixed doesn't require usage of the content-disposition header).This proposal aims to address these deficiencies.
Full example
This same spec would work also for
multipart/mixed
. However, for the case of multipart/form-data in particular, where every part is required to have a name, we have a convenience form that takes an object:This form is very similar to what we have today, but the values must be wrapped in
HttpPart
. So for determining the name of a part, the following is the precedence order:If none of these are specified, it's an error.
@multipartBody
This decorator is used in place of
@body
to signify a multipart request/response. It is an error for anHttpPart
to appear in a regular@body
. It is an error for amultipartBody
to be anything except an array ofHttpPart
s.HttpPart<TBodyRoot extends {}, TOptions extends valueof PartOptions>
The HttpPart has two parameters, the body root of the part, and options. The body root behaves identically to the argument list of an operation. It should always be safe to refactor an operation into a multipart operation by copying the parameter list of the operation into an anonymous model passed to HttpPart.
It is an error for a multipart/form-data part to specify the
content-disposition
header, as this is essentially fixed for this content type.File
The file type is a well-known type representing a File:
Usage of
file
is not required when uploading file contents for multipart requests. When merelybytes
is used, our existing behavior continues (which is essentially to treat bytes in a multipart/form-data request as if it were a File).File
exists for two reasons:Internal
@httpFile
Marks a model as an http file. Must have at least a
contentType
,filename
, andcontents
property.Deprecations
We should deprecate multipart/form-data with implicit or explicit body.
The text was updated successfully, but these errors were encountered: