I would use the envelope. Don't tie your data format to a transport protocol implementation details. If you suddenly decide you want to store and replay data payloads or put it through queue or something like that, you'll be in trouble.
If a particular client doesn't need the envelope, it can easily strip it out as soon as the response comes in from the backend.
What would you do in case the payload format doesn't allow for wrapping in an envelope because it cannot be extended like that, such as a paginated slice of a CSV data dump? Or a chunk of a binary data stream?
This is now veering away from web api design, where you would use json/xml over http in 99% of cases. The answer is, it depends.
For csv, I would probably not include metadata at all, but require recipients to obtain it using a separate method. For binary data, you would probably get metadata as part of the binary format itself. But yes, maybe also as headers in the transport protocol.
It depends.
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
I would use the envelope. Don't tie your data format to a transport protocol implementation details. If you suddenly decide you want to store and replay data payloads or put it through queue or something like that, you'll be in trouble.
If a particular client doesn't need the envelope, it can easily strip it out as soon as the response comes in from the backend.
Devil's advocate incoming :-D
What would you do in case the payload format doesn't allow for wrapping in an envelope because it cannot be extended like that, such as a paginated slice of a CSV data dump? Or a chunk of a binary data stream?
This is now veering away from web api design, where you would use json/xml over http in 99% of cases. The answer is, it depends.
For csv, I would probably not include metadata at all, but require recipients to obtain it using a separate method. For binary data, you would probably get metadata as part of the binary format itself. But yes, maybe also as headers in the transport protocol.
It depends.