When in my REST API should I use an envelope? If I use it in one place, should I always use it?

Question

I\'m working on building a RESTful web service. I have read up on the principles of using HTTP for every mechanism as far as it will take you, and most of the time, like whe

Answer 1

If by "I standardized an envelope to use for every request" you literally mean every request, not just the one you described, I would say don't do it. In REST we try to use HTTP juts like the Web uses it, not to built an entire new proprietary protocol on top of it like SOAP. This approach keeps REST simple and easy to use. If you are interested, I've put more related thoughts here:

http://theamiableapi.com/2012/03/04/rest-and-the-art-of-protocol-design/

This being said, it is OK to return detailed error description with a HTTP error code. You first instinct, returning 409 and additional error codes sounds pretty good to me. The reason 409 is better than the generic 400 is that the error handling path in client code is cleaner. Some unrelated errors can cause 400, so if you use 400, you will need to check if there is an entity body returned, what format is it in, etc.