adding some explanation of how the API works