Note about PUT/PATCH in introduction §

[Nayte91]

I didn't see the note and spent a lot of time figuring out what happens, because I was trying to Upload to an Existing Resource, and the note is not in this chapter. So I think it deserves to belong in the introduction paragraph.

[alanpoulain]

I'm not sure changing its place would solve the issue. IMO the issue is more "graphical": we don't have a way to highlight a note like the Symfony documentation.

[Nayte91]

By my experience, yesterday evening:

• Searched how to upload a file without exposing a new resource and found this page,
• Went directly to the "Uploading to an Existing Resource with its Fields" chapter without reading the "Uploading to a Dedicated Resource" one,
• Tried to achieve it and tested code with some PATCH requests on my existing Entity,
• Table flipped after 2 hours (╯°□°)╯︵ ┻━┻ ,
• Looked at it today,
• Found this very important note in the other chapter,
• Wrote this fix in approximately 45 seconds.

It's pretty straightforward, and as I don't think I made a major mistake by skipping an optional chapter, I still argue that this note must be in the introductory remarks rather than in a skippable section;

Unless I am mistaken, the note applies to all PUT/PATCH requests with a file to upload, not only if the upload is done to a dedicated resource. I would say ESPECIALLY when you try to upload a file to an existing resource; It's easy to deal only with POST and DELETE on a dedicated resource, but on a existing one, not having PUT & PATCH is overwhelming.

But I also agree that docs may need an icon for important notes :)

[alanpoulain]

Alright 🙂