Simplify the separate evolution of the API and the Schema

[timbunce]

WebAPI::DBIC defaults to the pragmatic approach of being a thin layer over your existing DBIx::Class schema. This is indeed very pragmatic and gives you an 'Instant RESTful API'.

However, time rolls on and your schema might evolve in ways that would break the existing API clients, like change the name or type or semantics of a field. Or you might want to create a new API that abstracts/hides some details of the implementation in order to then be able to change those details without affecting clients.

One (very minor) step would be to make it easy for a resource to specify a list of field name and whether each of those fields is included in a response by default, or can be requested via the fields parameter. (If a field isn't on the list at all then it could not be included in responses and would trigger an error if included in PUT/POST requests.)

At a deeper level, WAPID is very much about being an interface to the services and semantics of DBIx::Class schema, especially the handling of relationships. So arguably the right place to handle evolution is 'behind' the DBIx::Class API. In other words, document and encourage use of advanced DBIx::Class features like subclassing ResultSource classes (and/or use of DBIx::Class::ResultSourceProxy::Table and DBIx::Class::ResultSource::View).

We should develop a list of evolution use-cases and corresponding recommended approaches.