Of all the principals of REST, perhaps the most overlooked it Hypermedia as the Engine of Application State, or HATEOAS. This term tries to encapsulate several concepts together, but the primary is the principal of discoverability.
All future actions the client may take are discovered within resource representations returned from the server.
What does this mean for Keystone?
Keystone is currently a fairly simplistic application. It can issue tokens to users, and it can verify that a given token has been assigned to a user. Assuming for the moment that this is all we want to be able to do, we should be able to discover this from the top down.
Keystone listens on two ports: 5000 and 35357. Pointing a browser at either of these should be the start of the discovery process. Indeed, we see that the server returns three hyperlinks to us. The second and third links are for documentation, and lead us not to other resources controlled by the server, but back to docs.openstack.org. Only the first provides guidance, but it makes an interesting design decision. It points us to the sub url for a version of the Keystone library. On my development server, this url is http://localhost:5000/v2.0/. Submitting this URL only provides us with the same information again.
What should it show us? Lets forget for a moment that this service is specifically for programmatic use, and imagine instead that we are building a web based user interface. From previous experience, we know that the URL to request a token is http://0.0.0.0:5000/v2.0/tokens. However, this is specifically accessed via a POST action.
Lets ignore authentication for a moment. Keystone integrates authentication with token access. However, they are distinct options. If we remove the password value from the “request token” form we get something that accepts:
- The user that should be associated with the token. This can be the authenticated user, but there are use cases where it we might want to delegate the ability to create a token.
- This limits the scope of the token
So without authentication, other applications need a way to indicate that they should provide this data in order to create a token. For a webUI, this would be something like:
Aside from this being a functional form in its own right, it provides sufficient information to another system to indicate how to create a new token.
This form could easily be displayed in JSON:
This would could be extended with more information about fields types and so forth.
So from the top level of the Keystone site, once the user is authenticated and has passed down through the hyperlinks:
And clicking through to tokens:
Add New Token
These last two forms probably should only be shown if the content type is set to HTM or XHTML.
Right now, even if content type is set to HTML, Keystone resorts to XML. The first step is to add a marshaller for HTML alongside to the JSON and XML marshallers, and then to support each of the content types equally.
Should Keystone support HATEOAS? I’d say yes. It makes the system more transparent and less surprising. It will give the implementors a means to debug at the server level, while not denying them the ability to hit things programmatically or from the CLI. It will also, I think make the design more solid move forward, as it will be more visually obvious how the different members of the Keystone domain model fit together.