add a first draft of API-related guidance

This went through a lot of revisions. Originally there was a lot more technical detail on the API service but it became clear that that is better placed in the service documentation itself. As such this provides a high-level overview of what APIs are, how one knows if you're doing it right and what the API service provides.

Closes #6 (closed)