[views] /v1 views API contract (review aid for #694, not for merge)

[ruolin59]

Important

This PR is a reading aid, not a merge candidate. #694 is the change under review and the one that would merge. This branch reproduces only the API definition from it — the endpoints and the wire models — so the surface can be read without the surrounding implementation. Please leave review comments on #694 unless they're specifically about the shape of these files.

Extracted from #694 in response to the feedback that 5k lines gets a shallow review. 573 lines across eight files, no validator, no service logic, no test suite.

The endpoints

ViewsController — the five routes under /v1/databases/{databaseId}/views:

Verb	Path	Success	Privilege
POST	/views	201	CREATE_VIEW
GET	/views/{viewId}	200	SELECT
PUT	/views/{viewId}	200, or 201 on create	UPDATE_VIEW_METADATA
GET	/views	200, paginated	LIST_VIEW
DELETE	/views/{viewId}	204	DELETE_VIEW

ViewsApiHandler — the interface the controller delegates to, included so the endpoint-to-handler contract is legible.

The wire models

CreateUpdateViewRequestBody — viewId, databaseId, clusterId, schema, representations, sourceDialect, defaultCatalog, defaultNamespace, viewProperties, baseViewVersion. representations is a list of ViewRepresentation {type, sql, dialect} rather than a scalar sql field, so a second dialect can be added later without changing the shape.

GetViewResponseBody — the pointer and row-backed identity. SQL, schema and history stay in the Iceberg metadata file, which the client already reads through its own FileIO.

GetAllViewsResponseBody — paginated from the first release, reusing GetViewResponseBody for its elements populated with identifiers only. Views only ever expose a paginated list.

ViewErrorCode — all fourteen failure modes declared now, including the ones M1 never emits, so later milestones add behaviour without changing the enum. It selects an HTTP status and is never serialized; the shared ErrorResponseBody is untouched.

Privileges gains CREATE_VIEW, LIST_VIEW, UPDATE_VIEW_METADATA, DELETE_VIEW; single-view reads reuse SELECT.

Where the rest lives

Everything else is in #694 and is not duplicated here:

ViewApiContractTest	freezes every field set and JSON key set above
OpenHouseViewsApiHandler	the handler implementation
OpenHouseViewsApiValidator	structural validation
ViewsService / ViewsDisabledService	the stubbed service seam
ViewDto, ViewsMapper	internal model and mapping
audit redaction, dialect config, exception handling

For context on why the contract is shaped this way rather than following the Iceberg REST spec, see the feasibility comparison and the discussion on #694.