There are a handful of questions a user will (implicitly) ask when using your API:
- What actions can I do against this endpoint?
- How do I find the URLs for those actions?
- What information do I need to provide in order to perform this action?
- What permission do I need in order to perform this action.
Answering these questions can be automated. The user, and the tools they use, can discover the answers by working with the system. That is what I mean when I use the word “Discoverability.”
We missed some opportunities to answer these questions when we designed the APIs for Keystone OpenStack. I’d like to talk about how to improve on what we did there.
Continue reading