I guess what I object to is this concept of discoverability. No matter what, you need documentation to discover these initial endpoints, so why not document the

I guess what I object to is this concept of discoverability. No matter what, you need documentation to discover these initial endpoints, so why not document the whole API? SOAP had mechanical discover ability with WSDLs but it didn't really work. The reason REST won was because it was simple for humans to understand, which means mostly that the documentation is simple to read. As long as the URLs follow some simple consistent pattern that developers can implement without convoluted effort it should be fine, no need to follow some rigid philosophy. If the documentation is missing some key actions I doubt most developers are going to go poking around hoping to discover undocumented endpoints, they'll probably end up contacting the developer to tell them they're API is broken.