we have a number of pages which do most of the work in the controller, such as article listing pages which show 'cards' for child pages beneath them, using the contentrepository to get 10 cards say and then use a load more function to show more.
if you wanted to return these listing pages from the contentapi, how would you approach getting the data for them? as by default they would clearly not contain any of the data for the cards
There are many ways to handle that scenario.
You could register an IContentConverter (EPiServer.ContentApi.Core.Serialization) and IContentConverterProvider for your page type and add the associated cards to your API model in that way. There is limited information in the documentation on this: https://world.optimizely.com/documentation/developer-guides/content-delivery-api/getting-started/serialization/#ContentModelMapper
However, if this is reusable functionality that could be applied to many pages, it could make sense just to create you own cards API, something like:
Then you have complete control over your card model and you de-couple it from the page load.