commit b446055fc03927474885d2eb33c44115873411ef
author Edwin Kempin <ekempin@google.com> Wed Jul 17 09:57:04 2019 +0200
committer Edwin Kempin <ekempin@google.com> Mon Aug 05 15:35:47 2019 +0200
tree 748e1446f81b60561fc3d417fcbc42e8ece4fe04
parent 24d2d506130db8ab7e9fa90ee7ea5d055c70db21

Require REST endpoints to return Response<?>

At the moment REST endpoints can choose if they return a result object
(that will be converted to JSON automatically unless it is a
BinaryResult) or if they return a response object that specifies the
response status code and other properties like caching behavior in
addition to the result object. In addition REST endpoints can return
special objects like Response.Redirect and Response.Accepted to trigger
special behavior (Response.Redirect and Response.Accepted are neither a
result object, nor a response object).

If the first approach is chosen and a result object is returned, it is
not clear from the implementation of the REST endpoint which status code
is returned to the client. By default it is '200 OK', for
RestCollectionCreateViews that are invoked via HTTP PUT/POST it is
'201 Created' and for RestCollectionDeleteMissingViews that are invoked
via HTTP DELETE it is '204 No Content'.

By forcing REST endpoints to return a response object they must specify
the status code. Hence implementors must explicitly think about this.
Hopefully this leads to a more consistent use of status codes in our
REST API. At the moment it happens frequently that status codes are
wrong and need to be fixed, which is always a bit risky since callers
may rely on an expected status code.

Having all REST endpoints return response objects also has the advantage
that wrappers around REST endpoints, such as RetryingRestModifyView, can
set additional properties on the response. E.g. change I2b78cbef5
implements automatic request tracing in RetryingRestModifyView, but
currently has no possibility to return the trace ID to the client. If
that was possible, error popups in the frontend could display the trace
ID. If the trace ID is included into bug reports, investigation of
issues gets easier and faster.

Response.Redirect and Response.Accepted are made subclasses of Response
so that REST endpoints can still return them.

Change-Id: I1dd37821a8a859ade43336eb5f6cce6bcc71fc02
Signed-off-by: Edwin Kempin <ekempin@google.com>