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:

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

Implement standard in APIs:

• auth AUTH: Standardize API returns #250
• crypto Standardize API error return values #183
• network Network: return JSON problems instead of text/plain errors #273
• vcr VDR & VCR: update docs #354
• vdr VDR & VCR: update docs #354
• update docs, add API error details VDR & VCR: update docs #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?