The updates to the API are appreciated, but I don't like the tone of some of these comments. Perhaps just put a comment after the lookups by filename which indicates: # lookups by id are more efficient, and provide an example of lookups by ID (you already do this).