Open tisto opened 7 years ago
Do we want to provide a error format suggestion in plone.rest? And if so, should it be different to the common format in plone.restapi?
When implementing it we should keep in mind that plone.restapi still announces providing non JSON responses later.
Beside documenting it and unifying our code we should:
e.g.
in a utility function to create the error json (dict)
def error_json(type, message=None, extras=None)
where extras is a dict that updates the default errors dict.
and a method of plone.rest.Service
and/or plone.restapi.Service
to set the status and return the json
def error(self, type, message=None, extras=None, status=400):
To make the usage in a Service class easier
from plone.rest.exceptions import HTTPError
if FAILED:
raise HTTPError('Bad Request', 'missing or invalid Content-Type header')
The signature should look something like
class HTTPError(type, message, extras=None, status=400):
plone.rest.RestService.__call__()
should handle those exceptions.
We might want to look into hydra error responses: https://www.hydra-cg.com/spec/latest/core/#description-of-http-status-codes-and-errors
RFC 7807 might be a good option:
https://blog.restcase.com/rest-api-error-handling-problem-details-response/ https://tools.ietf.org/html/rfc7807
We will discuss this at the Beethoven Sprint.
We do not document our error handling (possible status codes and messages). In addition our current implementation is inconsistent, e.g. an error on the @login endpoint encapsulates the error type/message within an error attribute:
https://github.com/plone/plone.restapi/pull/164/files#diff-ba94937d2482a112f9b033a9a89deb4bR40
while an unauthorized request on a private document returns a top-level type/message json structure:
https://github.com/plone/plone.restapi/pull/164/files#diff-ba94937d2482a112f9b033a9a89deb4bR117