Some updates (hopefully correct!) to the api.md documentation

Some changes to the api.md documentation, mostly around clarifying the v4 API.