Reorganize and streamline form media type guidance (3.0.4) #3923
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This just moves (and occasionally copies) blocks of text and/or examples in preparation form more substantial streamlining. No modifications were made to any block.
Make the Parameter, Encoding, and Header Object fixed fields section organization the same in all three places, with the same levels of indentation. Add more headings under the Encoding Object for guidance on each form media type, and sub-headings for each example in each of those sections. This will make the diff for the next commit much more legible.
This puts the useful part of the "An encoding attribute..." text into the fixed fields table, and removes the duplication. It also links the remaining stub or truncated sections to the information's new location under the Encoding Object.
This re-organizes and streamlines the form-urlencoded guidance that was consolidated from the Media Type Object. It also adds an example of a base64-encoded URL query parameter.
handrews
added
clarification
This was referenced Jun 20, 2024
ralfhandl
previously approved these changes
Jun 20, 2024
This organizes and streamlines the guidance on multipart that was incorporated from the Media Type Object. Lots of duplication has been removed, and the examples reworked to show distinct use cases.
mikekistler
reviewed
Jun 20, 2024
I forgot to run the example through URL quoting, which is necessary.
|
I've added two more commits (and edited the commit list in the PR text above) that fix an error in the base64 example and restore a paragraph I didn't mean to delete. (@mikekistler I doubt it makes things more clear, but it's more correct). |
I did not mean to remove this.
ralfhandl
reviewed
Jun 21, 2024
ralfhandl
approved these changes
Jun 21, 2024
mikekistler
reviewed
Jun 23, 2024
miqui
approved these changes
Jun 23, 2024
|
@miqui @mikekistler had asked for changes here, and the discussion was not resolved. This should not have been merged and I consider it to still be open for changes. @mikekistler perhaps to avoid future confusion it would be best to use the "request changes" button in the review interface even if it's not yet clear what (if any) changes would be requested. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
It's probably best to look at this as individual commits-
gitis pretty confused about the overall diff so I went back and divided it up into five separate steps:form-urlencodedform-datacontentMediaTypeThere has been a lot of duplication around
form-urlencodedandform-databetween the Media Type Object and the Encoding Object.Figuring out form details has required reading through both sections, because some things only appear in one place, some only appear in the other (and not necessarily the way you'd guess), and some things are in both places but contradict each other (#3921 includes a fix for one in 3.1.1, #3922 fixes a similar problem in 3.0.4).
I've opted to handle everything under the Encoding Object, particularly as we have clarified that an absent
encodingfield in the Media Type Object is the same as having it with empty Encoding Objects for every field. I've kept the old Media Type Object section headings and linked to the new sections for folks who might be used to looking there.I've given each example a section heading because they do distinct things and it's helpful to see that in the TOC.
Porting this to 3.1.1 will have to wait for PR #3921 to be merged, and it will also be similar but not quite identical because of the differences in handling binary data.