This is probably my number one criticism of most "REST" APIs out there - they are horribly non self-documenting, and the effort required to make them self-documenting is really fairly trivial:
1. Ensure that you have a URI to the resource in question every single time you reference an ID somewhere (in collections, when referencing resources from another resource)
2. Make the root of your application document all the collections available and their respective URIs.
3. Include paging URIs as mentioned in the article.
4. If a resource has nested collections, include URIs to them in your JSON representation of the resource.
Boom! You now have a REST API better than 99% of what's on the web today.
Yes, what you describe is true. We also had a good discussion a few days ago about scenarios where REST doesn't seem to work well. The specific problem is when things start getting too chatty. Its very difficult to expose a flexible (fine-grained) REST API and at the same time give you all the data you need in the least amount of calls. It takes quite a bit of work up front to figure out what your model is going to be and figuring out if that model will work for most of your consumers. Getting the 'pattern' down as you described is half the battle.
1. Ensure that you have a URI to the resource in question every single time you reference an ID somewhere (in collections, when referencing resources from another resource)
2. Make the root of your application document all the collections available and their respective URIs.
3. Include paging URIs as mentioned in the article.
4. If a resource has nested collections, include URIs to them in your JSON representation of the resource.
Boom! You now have a REST API better than 99% of what's on the web today.