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

I think like many specific cases in REST it's up to you. I look to the web to for examples. For example when you go to a web page or URL that doesn't exist in the WWW you normally get a 404 and an HTML page that page usually has hypermedia to some resource. This hypermedia is what the service thinks you are trying to get to or may be the a home page {bookmark url}. In machine to machine REST senarios may not be using HTML as the media type, but you can still return a resource that 1) provides details on the error and 2) provides hypermedia to a valid resource

The 409 is an error code that you don't see much of in the wild WWW therefore you are kind of on your own. I use the 404 as a parallel and return a resource of errors like you are doing and also hypermedia to the resource that caused the 409 in the first place. That way if they intended to create the thing that caused the conflict in the first place they can just get it.

We did standardize on what error resources would look like so that clients would know how to consume the error. This of course is documented by following the rel in the resource.

In your specific case of "nickname or an email address" I could see using a 400 or a 409 because that is just one piece of information of the resource.

Also we don't have 1 single envelope. We use http://stateless.co/hal_specification.html and the resource is either what they asked for or an error.

HTH