Implement RFC7807: Problem Details for HTTP APIs

[gerardsn]

Following #3 and #9 we propose to implement RFC7807 to standardize API error handling. More specifically, define "Title", "Status", and "detail" members for each problem.

One of the current methods used is

func (a Wrapper) GetDID(ctx echo.Context, did string) error {
    d, err := did2.ParseDID(did)
    if err != nil {
        return ctx.String(http.StatusBadRequest, fmt.Sprintf("given DID could not be parsed: %s", err.Error()))
    }
       ...
}

which can be standardized using https://github.com/mschneider82/problem to something like

func (a Wrapper) GetDID(ctx echo.Context, did string) error {
    d, err := did2.ParseDID(did)
    if err != nil {
        p := problem.Of(http.StatusBadRequest)
        p.Append(problem.Title("given DID could not be parsed"))
        p.Append(problem.Detail(err.Error()))
        return p
    }
       ...
}

This will require:

• [x] research on how to include external schemas in API generation #183
• [x] add general return for status 500 #183
• [x] add standard for error handling status >= 400 #183

Implement standard in APIs:

• [x] auth #250
• [x] crypto #183
• [x] network #273
• [x] vcr #354
• [x] vdr #354
• [x] update docs, add API error details #354

[woutslakhorst]

@stevenvegt @reinkrul thoughts?

[reinkrul]

I think this can really improve the consistency of our REST API and I'd really like our error responses to be JSON as well. We should take care we don't introduce a massive amount of code or complexity though (while implementing). Proposal looks good, though we should discussing collapsing the builder calls;

return problem.Of(http.StatusBadRequest).Append(problem.Title("given DID could not be parsed")).Append(problem.Detail(err.Error())) (something like that)

Also in this case, I'd say the title should identify the operation that was performed, and the detail what went wrong. Now they're a bit duplicate?

So title could be something like "can't resolve DID" and description the parser error? Or does the RFC state otherwise?