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:

userid

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.

tenantId

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.

The URL of the token validation is of the form  http://0.0.0.0:35357/v2.0/tokens/$TOKEN,  we would want a form that allows the user to submit that value.  A form can do a Get action, but it cannot rewrite the target hyperlink without Javascript, something we would avoid here.  We do not want to enumerate all tokens, as that would wrongly expose shared secrets.  Thus, a post to an URL with a parameter of the token ID, as well as any other identifying information required would be more useful.  This would be token id,  user id, and tenant id.  The HTML response code would be 200, and the body of the response would indicate valid or invalid.  This post could also return a hyperlink to the original  URL  of the form http://0.0.0.0:35357/v2.0/tokens/$TOKEN,  and that URL would still be accessible via HTTP GET.

This form could easily be displayed in JSON:

{"fields":["name","userid","tenantid"]}

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:

Tenants
Tokens

And clicking through to tokens:

abcd
fghi


Add New Token






Validate 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.