The habit of relying in preference on examples has nothing wrong: for you, it's just the fastest way to get your answer. Moreover, examples are visual. It's easier to parse visually an example rather than read paragraphs of text and extract the information you need.
In order to list the products, one should use
Index action of the
Products controller, given that
GET is the only possible verb here (see [Affecting products] for more information about the actions used to create, modify and delete the products from the database).
In order to obtain detailed information about a specific product, append its unique identifier to the end of the URI. If you want to get the list of every product available, don't append anything. You may also use filters, as described in the [REST filters for selecting data] section of the manual. Note that the list of products is limited to one thousand items. [Pagination] can be used to walk through the entire list, given that each page is still limited to one thousand items.
You may also want to force the service to refresh the quantities in stock. This is done by setting the
refresh-quantities to one.
is detailed, but boring and barely readable. The fact that you need to follow links makes things even worse. If we append some samples, it becomes much easier to understand:
The fact that you use only the examples may be a problem. Don't plainly stop using the examples, but remember that once you got the idea, a more verbose documentation may help. For example, the sample above doesn't show that the list of products is limited to 1 000: you have to read the documentation for that.
When do you know that you should read the documentation?
Every time the API or the library is not behaving as you expected. For example, you grab the sample and do:
For some reason, it returns less than 3 000 items, while you have over twenty thousand products in your database. Here, the API is not behaving like you expected, so it's a good time to read the detailed documentation.