jsonapi: Export Errors

[256dpi]

As only two of many errors are exported, they will be removed with #261 to be concise.

This issue should track the discussion about how errors should be exported again and therefore handled in calling go applications.

From a quick scan I came up with the following classes of errors:

• Bad Payload (wrongly formatted JSON API documents)
• Invalid Target/Source (required implementation of interfaces and type)
• Nil Argument (some arguments must not be nil)

I would suggest that we exports these classes of errors:

var ErrBadPayload = errors.New("bad payload")
var ErrInvalidSource = errors.New("invalid source")
var ErrInvalidTarget = errors.New("invalid target")
var ErrNilArgument = errors.New("nil argument")

Afterwards we could wrap the errors and add additional context for logging:

return errors.Wrap(ErrInvalidSource, "all slice elements must implement the jsonapi.MarshalIdentifier interface")

The wrapping approach ensures the clean error interface for applications that have no special interest in the errors. Applications that do want to know the cause of error can use:

if errors.Cause(err) == jsonapi.ErrInvalidSource {
  // ...
}

Some Links to this approach:

• https://godoc.org/github.com/pkg/errors
• https://www.youtube.com/watch?v=lsBF58Q-DnY

[sharpner]

Although I really like pkg/errors I am not sure if a library like api2go should force such a framework onto the user, even if its small and helpful. I think we should expose simple standard library errors, as you suggested in your first paragraph, but without the wrapping part.

[mwmahlberg]

I agree that standard errors should be used. Additionally, helper methods like os.IsNotExists could be provided. This would make error handling very straightforward.