Object relationships in API responses are inconsistent and unexpected

[longhotsummer]

We don't explicitly detail what should be returned by the API ito object relationships. This means that when you ask for https://api.pmg.org.za/committee/77/ for example, you get tabled committee reports and events nested, but not other nested relationships. This is both confusing and, at times, annoying if you don't want all that extra data.

Our serialisation code is home-grown and has weird edge cases like loops.

I'd like us to re-explore how we do serialisation in the API and be more explicit about it, with these goals:

• we're explicit and consistent about returning nested relationships vs links.
• use a 3rd party serialisation/schema package like marshmallow which has adapters for Flask and SQLAlchemy
• allow the caller to specify what fields they want ala JSONAPI's sparse fieldsets. This is useful when we, say, want to load titles, dates and ids of all committee meetings for a particular committee, but don't want the summary and body (which are big). Marshmallow has rich support for this
• version the new api under /v2/ or similar.

I've looked at Flask Restless but it's undergoing a major rewrite and there are a few others but nothing is very promising. So, rather than totally rewriting, I think we should focus on achieving the changes above which have benefit to us in the short term.

[longhotsummer]

I'm hoping we can get the bulk of this by deferring to marshmallow for the serialisation and specifications, and a little wiring around the flask call (similar to what we have now) to handle pagination and processing query params.

[longhotsummer]

I'm working on this in https://github.com/Code4SA/pmg-cms-2/tree/apiv2 using the fact that the committee detail page loads very slowly as the user-facing driver. With this change, we can specify which fields we want, which makes the page load much faster.