Embed more error information into the message.

[jgornick]

Would it possible to embed more error information into the response body instead of via _links. My assumption is that links usually point to static content, however, errors will most likely reference dynamic resources.

To expand on the validation error message, there's nothing there that describes what failed. The GitHub API implemented a way to provide more information about the validation error: http://developer.github.com/v3/#client-errors

Thoughts?

[blongden]

An obvious approach would be to just add another optional field - 'errors', containing an array of message/field/code, though I am not sure yet if that's the right approach - it could look like this:

{
  "logref": 42,
  "errors": {
    "code": "too_short",
    "field": "username",
    "message": "Must be at least 3 characters in length"
  },
  "message": "Validation errors"
}

Alternatively, and possibly to add more flexibility, we can just add 'code' and 'field' fields at the top level, and simply embed more error objects as required in a defined link relation (errors):

{
    "message": "Validation failed",
    "logref": 50,
    "_links": {
        "help": {
            "href": "http://.../"
        },
        "describes": {
            "href": "http://.../"
        }
    },
    "_embedded": {
        "errors": [
            {
                "message": "must be at least 3 characters in length",
                "code": "too_short",
                "field": "username",
                "_links": {
                    "help": {
                        "href": "http://.../"
                    }
                }
            }
        ]
    }
}

[blongden]

I think I prefer the second option.

[pnsantos]

Yes the second option is also imo the prefered one.

BTW according to HAL all resources should have a self link and any embedded resource should have it's link relation present in the _links element. So shouldn't the example be instead like this?

{
  "message": "Validation failed", 
  "logref": 50, 
  "_links": {
    "self": {
      "href": "http://.../"
    }, 
    "help": {
      "href": "http://.../"
    }, 
    "describes": {
      "href": "http://.../"
    }, 
    "errors": [
      {
        "href": "http://.../"
      }
    ]
  }, 
  "_embedded": {
    "errors": [
      {
        "message": "must be at least 3 characters in length", 
        "code": "too_short", 
        "field": "username", 
        "_links": {
          "self": {
            "href": "http://.../"
          }, 
          "help": {
            "href": "http://.../"
          }
        }
      }
    ]
  }
}

I only see a problem with this. The self link of the error is tricky to implement as it's a "volatile" resource, i.e. it only makes sense (in some cases like field validation errors) to a specific request and as such having a resource to represent something so short lived isn't worth the effort imo (but HAL nevertheless forces representations to have a self link...),

[JornWildt]

I only see a problem with this. The self link of the error is tricky to implement as it's a "volatile" resource.

Seems to me like a really good argument for not making it an embedded resource.

[pnsantos]

Now that I think about it if you consider the self link of root element to represent a specific validation error combination it does indeed becomes tricky to implement as it's bound to a specific request where a specific combination of invalid fields was submitted.

If however the self link only represents a generic "validation failure" then it's ok. I don't know however if this would be inline with HAL... can we have the same self link have at different times different embedded resources?

[jgornick]

After reading through the discussion, I think I'm with @JornWildt. errors should be an optional property in the error message schema as opposed to an embedded resource.

So, I prefer:

{
    "logref": 42,
    "errors": [
        {
            "code": "too_short",
            "field": "username",
            "message": "Must be at least 3 characters in length"
        }
    ],
    "message": "Validation errors"
}

[andresf]

Well, the HAL spec has it as a SHOULD, so it's not strictly mandatory. I'd say this is a valid edge case to warrant ignoring the self link. However, if the spec changes then compatibility would be lost.

[pnsantos]

my bad yes you're right (don't know why but I though it was a MUST)

[jgornick]

I think the question to ask: Is each error in errors a "Resource Object"?

If you answer no, then the errors should be an optional property in the message schema.

After reading the _embedded and "Resource Object" sections in the spec, I don't think these errors are embedded resource objects.

[jgornick]

I was just looking through the other issues and noticed that #9 is very similar to this issue as well.

[fosrias]

@blongden Per our discussion at RESTfest, I add my comments here. One of the things we considered a shortcoming in vnd.errors was the inability to send custom error codes and error parameters in our enterprise platform with the current spec. There are two primary consumers of error payloads of API requests that I am addressing:

1. The debugging developer: really just cares about an error message that can be passed to logs and it can all be in english so they can figure out what is going on, but having custom internal codes that could be logged to relate things would be useful.
2. The presentation layer developer/api consumer developer: Cares about passing localized error messages to the client. To this person, debugging messages are useless because they want to render a useful error message to the end user, possibly with the offending data interpolated in the message. And in their language.

Assuming an internationalization service (client side library) with error codes that could render interpolated messages given parameters, this allows client developers to know how to render accurate error messages without some unreliable parsing of a message.

As such, based on the discussion above I would think about a slight modification to the example like:

{
    "logref": 42,
    "errors": [
        {
            "codes": "must_match 1234 AVRX",
            "fields": "username email",
            "values": "bob@example.com bob@example.org"
            "message": "Are not the same."
        }
    ],
    "message": "Validation errors"
}

Client can parse the codes associated with the individual errors and handle the ones it understands. Alternately, just add a value field and keep code and field and allow them to be space delimited in the spec. With that information, a client developer can render some nice localized error messages based on the error in the API. My two bits.

[hjr3]

I agree that the field level specific errors should not be embedded. They are not really resources. As such, I am 👍 on the second option that @blongden provided.

I am 👎 on space delimited strings for multiple values. If we want multiple codes, then allow the spec to have a single code or list of codes as valid entries.