Often, you need some extra advice in order to make a decision regarding your API.
Having designed and reviewed thousands of APIs I can provide some expert advice.
Please always include:
* Who is going to use the API? f.e. a librarian.
* What are they trying to achieve? f.e. create an index of all the books in the library,
* How are they going to use? f.e daily export of all the books.