states: transfers and representations
over the last several weeks, i've been working on a number of hypermedia designs.
some of these are for clients' production implementations but many of them are
just explorations of the design patterns and constraints; ways to learn how to
effectively and efficiently express a problem domain within a hypermedia type
design.
it's been a very interesting experience!
what follows are my notes and observations about an ongoing process of discovery related to designing and implementing hypermedia-driven solutions. some of this is direct recounting of my experience (including interaction w/ devs, etc.). most of it is idle talk and musing borne of my own personal assumptions about anecdotal observations and feedback.
conceptual elements
as i work through the various designs, i am finding that my personal style leads to a focus on two key conceptual elements: representations and transfers. these names might not be the best as they are rather ambigous, but these are the 'labels' that are working in my head right now.
representations
representations are the responses from servers that express the current start of an identified resource. a response might represent the list of open orders, a single users' profile, the result of an attempt to update an existing customer record, etc.
some folks think of a representation as a 'web page' or as an 'object graph' from the data store. i think that mental model is too limiting. it leads devs into designing resouces and crafting URIs to reach them. to me this is going about it in the wrong way. my approach is to identify the state that needs to be represented (the user list, the composite of todays news, a complete invoice, etc.). this representation might span several storage collections/records. it might not exist as any single stored entity at all.
transfers
the act of representing the current state of an identified resource is relatively straight forward. what does a "user" need to "see" when they make a request? the more interesting work (to me) is enhancing that state representation with one or more transfer options. client-initiated state transfers allow the "user" to *do* something (navigate to a new page, filter the data, search for other data, etc.).
typically, transfers can be simple (they don't need any arguments) or 'complex' (they include one or more arguments that are passed to the server with the request). simple transfers can be represented as links in the response:
{"link" : {"href" : "...", "rel" : "users"}}
complex transfers can be represented as a template; one that includes both a URI and one or more 'input' elements (some of which might be pre-filled and/or read-only).
{"link" :
{"href" : "...", "rel" : "users"},
data [
{"name" : "first-name", "value" : ""},
{"name" : "last-name", "value" : ""),
{"name" : "status", "value" : "new", "read-only" : true}
]
}
my transfers are always marked with an identifier (usually named "rel" to take advantage of the 'shared understanding' that comes from the HTML.A.@rel pattern). client applications are "taught" to pay attention to the identifier, not the URI. my client applications are essentially 'coded for rels.' it's the rel that is interesting|meaningful to the client apps i write.
expressing a problem domain via transfers and representations
the process of expressing a problem domain is the process of identifying and designing each representation and transfer that is needed. it's not very complicated work, but it does require attention to detail. the process goes relatively smoothly when i am using a base format (HTML, JSON, XML) that already has solid support for H-Factors, too. this is especially true when crafting transfers.
as i go through the process of designing representations and transfers, i end up with a collection of them; each one providing a needed solution for the problem domain. the aggregate of these representations and transfers make up the 'complete' expression of the target domain; the implementation at the message level. essentially, this is the hypermedia application.
no flowcharts, no arrows, just states
one of the (many) key revelations for me in this process has been the realization that i do not find flow charts or detailed 'arrows and boxes' very helpful in either documenting or representing the problem domain. this may just be my own POV, but i find the collection of representations and transfers appear to me as a set of independent (stateless) 'bulding blocks' that can be assembled in various ways to successfully express just about any scenario of representation response and transfer request options that might be needed for the problem domain.
even more interesting (to me) is the discovery that these transfers and representations can be cobbled together in ways that i didn't (at first) consider. i find that some devs, working with the media type design and the list of representations and transfers, are crafting new 'work flow' and 'processing' chains that were not initially described in discovery. the media type is 'leading' devs into discovering new ways to provide the users w/ the representations and transfer options needed to solve 'new' problems.
the design is evolving even at the early stages.
what deoes this all mean?
so, as i progress through trial and error, i am building up a body of knowledge; a set of practices that work in many cases. i am also discovering that some of my assumptions about how things work, how devs approach solutions and how users evaulate the results are not always right; i have some bad assumptions!
right now that body of knowledge is pretty basic:
- focus on transfers (requests) and representations (responses)
- work through the problem domain to identify all the transfer/representations needed
- use a base format that supports the H-Factors needed to handle the transfers
- treat transfers and representations as 'stand-alone' building blocks
- allow devs to use the blocks to craft responses that meet users' requirements
- as time goes on, continue the same process and allow the implementation to evolve
i don't present this as 'fully-baked' concrete practice; just as my own ideas on what i've learned and how things play out as i go along. hopefully these notes will be helpful as you make your own journeys through 'hypermedia-land.'