Error handling is inconsistent and undocumented.

[tisto]

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

[csenger]

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:

provide an utility function

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

provide HTTP Exceptions:

    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.

• set status code and reason
• raise an exception to abort the transaction
• Attach the correct json body to the exception.

For comparision:

• Pyramid
• Cornice
• Dango Rest Framework
• Flask

[tisto]

We might want to look into hydra error responses: https://www.hydra-cg.com/spec/latest/core/#description-of-http-status-codes-and-errors

[tisto]

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.

[davisagli]

These days, plone.rest provides a standard error view for exceptions that are raised. So, for example, a REST API service can raise zException.BadRequest, and plone.rest will take care of serializing it as JSON in a standard format.

There is also a PR in progress to add support for translating exception messages if they are created with a zope messageid: plone/plone.rest#201

We should merge that, and then update plone.restapi services to be more consistent about raising actual exceptions with a messageid instead of trying to handle their own exception serialization.

[tisto]

@davisagli sounds good. We just have to be aware that this will most likely be a breaking change.