Service descriptions - servers describing their supported features and endpoints

[joepio]

I was working on creating tooling for Versioning for Atomic Data. I want to make this functionality discoverable for users, for example through a menu or a button on the resource. But... Not all atomic data servers will have this feature. And even if they do, how would the front-end app know?

Check hard coded endpoints

In this case, we could say that all /commits endpoints should point to the commits endpoint. However, this would severely limit implementations and users in their choices for endpoint names, and it would make extending endpoint functionality impossible to do consistently. Not good.

Paths and endpoint descriptions

Paths can be really useful to provide a predictable way to find specific things on a server. For example, finding the first name of the owner of a server might look like profile first-name. Similarly, the path to the commits service might be found with endpoints commits. Now, the resource resolving to that path may be available on example.com/commits, but this is not required. The resolve mechanism traverses resources, instead of using a predictable URL.

So, the front-end requests the root resource (the Drive), checks the endpoint resource. When the required endpoint is there, the front-end will show the action.