Roy Fielding wrote this post recently on the proliferation of APIs that claim to be REST but are breaking some of the fundamental constraints of a REST style architecture.
I was most struck by what Roy seems to be saying is required to document a REST Api.
- A description of the media types that are used throughout the API.
- A root Url.
That is it. If you look at most API specs you will see a long laundry list of the endpoints that can be used to access various pieces of functionality. In REST, you don't want to provide a list of endpoints because then you are allowing the client to bake that knowledge into its implementation. That's coupling.
I'm going to reach a little here and add some of my own conclusions. You can couple on the media types. If you need to create your own media type to allow the client to process the data on the server, then so be it. At some point the client has to understand what to do with the data it is being sent.
However, don't couple on endpoints, there is really no need. Use the root url to deliver some kind of discovery document that allows the client to find the other available resources.
It's kind of like how a web site works... :-)