I'm trying to better understand the pros and cons of REST. I think I have a pretty good hold on the core factors, particularly creating endpoints/URIs that better represent the resources in play and using hypermedia to eliminate coupling of clients and the URIs to the application
My understanding is that if clients are interacting with the REST application properly, they are always accessing the base endpoint and using the hypermedia returned to direct them to the resources they want to interact with. Some knowledge of what will be returned is required though, since the specifics of the hypermedia used or what the relationships returned mean. A calling application needs to know, for example, that it was want to go to the "create" URI and do a PUT there to add a resource.
This seems reasonable enough, though, since the URI returned with the "create" relationship can change at the discretion of the server and the client will still be able to add the resource. However, what happens when that resource required a considerable amount of metadata? How does the client know what data is required and how to provide it? Does this all need to be provided to the client separately? It seems like it must have to be, the client can't magically know that information.
If that is the case, however, it seems that the primary thing we're getting from REST is that URI independence. Something that, though certainly valuable for some applications seems like it's probably not worth the overhead required for both applications in most contexts. Am I missing something here? What level of documentation and knowledge-sharing is expected to be shared with the client before they can call the service?
It occurs to me in part that I may just need to see an service I know is truly RESTful and learn from how that is architected. Are there any great public examples of a RESTful service that I could look at to help better understand this?