Just look at the issues , how they handle them , how their professional responses , and how quick they resolves issues after issues with full co-operation between issue owner , users and contributor. They guide contributors as well. And it is really Addictive , be warned.
I really can't give you a concrete answer but I wanted to confirm what my GP said:
I must admit to being obsessed with their GitHub Issues for awhile. It was almost as addicting as HN or reddit to check and read new issues and comments - I've probably read every major discussion and minor interaction they've had over the last year or more.
I saw that, but I'm still a bit confused. Is it saying that if you have two volumes using this system then one will be a copy of the other? Or some data will be on one volume and some will be on the other, but both volumes will look like they have all the data?
Pure REST is great for toy examples, where every domain entity fits neatly into a resource and every operation is a CRUD one that can be represented as an HTTP verb. So there is a million tutorials explaining how to build a REST API for a blog with BlogPost and Author resources, or an ordering system with Customer and Order resources.
In my opinion REST is fat more easier to understand for non-CRUD resources. The whole idea of CRUD makes REST sometimes seem like an HTTP adapter to the database.
However, when you move beyond these simple examples and start trying to build a REST API for a messy, complex system, you immediately run into trouble. How do you deal with non-CRUD operations? How do you deal with long running processes?
You POST the work to be done to a resource. That resource returns a URL where you can follow the state of the long running process. An alternative would be to provide a Webhook that will be called when the long running process has finished.
Or entities in an indeterminate state?
Same principle, return its actual state on a GET request (polling). Or use a Webhook (push).
How do you aggregate multiple resources into individual request/responses for performance?
Use HAL embedding or multipart.
How do you de-duplicate identical entities within an aggregated response?
Use the hypertext caching pattern in your caching layer or proxy. Use the URL as a unique key.
How do you return only particular fields?
Use HAL embedding, query parameters or a subresource.
How do you handle paging and filtering?
Use link relations and query parameters.
How do you handle transactions?
That's exactly what POST is for.
How do you handle authentication and security restrictions?
Provide a token header over https. Avoid magic URLs based on cookie state (i.e. even when you are logged in as mike your account details still are at https://example.org/user/mike/account). Restrictions are a product of the token and the requested URL.
All of these things can be solved, but by the time you've finished, your API will be far from easy to understand.
That is true, it won't be easy to understand, but it will be simple, composable, discoverabe and scalable.
It will need a load of accompanying documentation to make it usable
In my experience the opposite is true, true REST (which includes hypermedia controls) need less accompanying documentation. It makes resources more predictable and less dependendent on URLs.
All of these things can be solved, but by the time you've finished, your API will be far from easy to understand. It will need a load of accompanying documentation to make it usable, and will have a bunch of weird corners where you're initiating operations as a side effect of setting entity flags, or you've noun-ed verbs in order to turn an abstract operation into a resource. E.g. PUT /server-reboot-attempt.
In stead of making a separate resource for every action it would suffice to make one that receives actions by POSTing to it. You can respond with a URL that represents its progress. And it will also save a lot of unnecessary links or hardcoded URLs.
Most O'Reilly books about REST are really good.
If you want to be more practical I suggest looking for simple ways to introduce hypermedia controls. In my opinion the HAL JSON standard is the easiest to understand: https://www.google.com/search?q=hal+json