level = (instance|service|media)
"I'm completely changing the configuration of the apartment. Whole new life-style! Levels!"
"Levels?"
"Yeah. I'm getting rid of all my furniture. And I'm gonna build these different levels..."
"I don't see how you can get comfortable like that."
"Oh, I'll get comfortable!"
it's easy to get comfortable with the way things usually are; the familiar. this is true whether it's
the furniture in our apartment or the way we build client-server applications.
many programmers are familiar with a client-server application development process that focuses on one particular implementation - the one they are currently using or designing at the time. programmers may also think of modeling thier work from the same perspective - at the "instance" level. IOW, they see all implementations as "instances" of a service or Web application.
however, it helps me to identify three discreet ways to model client-server interactions for Web-based implementations: 1) Instance Level, 2) Service Level, and 3) Media Level. each of these levels is based on a greater degree of abstraction. in my experience this added abstraction, while a challenge, has the potential to offer increased evolvability and stability for applications running on a distributed network (e.g. Web applications) over the long term.
Instance Level Modeling
Instance Level Modeling (ILM) usually focuses on a single implementation of a Web application or service. documentation for this type of model usually includes quite a bit of detail on URI construction and a good deal of prose on how clients are to use these URIs to read and write data to the server.
as a result, client applications tend to have the URIs and semantic details "baked" into the client code. this makes it relatively difficult to change server implementation details in the future. for example, the server may not be able to change the request URIs for one or more data calls without first notifying all the client applications of this change so that they can update their source code and re-deploy. also, changing the order in which operations occur (e.g. workflow, etc.) or adding/removing elements in the requests and responses may break existing clients since these changes were not anticipated and could not be included in either the documentation or the client code that was created from that documentation.
most Web-based APIs that i see today use this model.
Service Level Modeling
Service Level Modeling (SLM) usually focuses on a general implementation of a Web application or service. documentation for this type of model usually includes a small number of URIs (e.g. one or more "entry URIs") and a response format that includes additional URIs in the messages.the documentation also instructs clients on how to locate and interpret these URIs when attempting to execute additional operations.
because of the more generic descriptions found in Service Level models, clients built for one implementation of the Web service have the potential to work for other implementations of the same API without much modification. depending on the documentation and the client implementation details (e.g. object serialization, etc.), changes to the content of the messages such as adding/removing data elements are not likely to break existing clients. however, changes in workflow might be ignored by existing deployed clients. this inability to honor workflow modifications dictated by the server may render existing client applications useless if that same server makes supporting those changes an operational requirement.
i do not often find Web-based APIs that use this model
Media Level Modeling
Media Level Modeling (MLM) focuses not on specific instance or a general implementation of a Web application or service. instead, the MLM approach focuses almost exclusively on the message (media) sent between parties. it's the message format that tells clients and servers what can appear within the requests and responses (e.g. what is valid). it's the message itself that contains the application controls that tell clients what can be read from, or written to, the server and how the application-level protocol can be used to execute these reads and writes properly. documenting MLM implementations means documenting the message's shared data format, rules for locating URIs within those messages, and rules for identifying the application controls that implement the media type's read/write semantics and workflow options. in effect, documenting MLM means documenting a flexible, evolvable "rich message" format that can be understood and shared by any server and/or client application.
crafting requests and responses that carry this "rich message" information can be done by designing and documenting MIME Media Types. media-types make it possible to adequately communicate read/write semantics (which elements are writeable, which protocol methods to use, etc.). these same media-type messasges offer the possibility of communicating context-aware workflow options (e.g. which "next steps" are available at this moment, based on your current context, etc.). when the media-type is capable of carrying this "message rich" information it can be though of as a Hypermedia Type.
because hypermedia types carry the details of possible additional client-server interactions (state transfers) within the responses themselves, client applications that understand these types are capable of quite a lot. clients need not carry URIs in the source code (except possibly a starting URI). clients need not track information about which messages formats are associated with which URI (since the media type IS the message). clients need not have the rules for reading and writing data (the read/write semantics) baked into the code since that, too, is carried within the responses sent from the server. finally, the workflow details need not be frozen within code nor does it need to be documented as a separate set of static rules since the response message can carry the available interactions based on the current context for a particular client request at runtime.
in addition, clients written to understand a media type (e.g. MLM clients) can work with several different existing services (SLM) and any single server instance (ILM) that uses a [hyper]media type as the message format. that means the the same client application can cover all the previous model types i've outlined here.
currently, the most-used client that meets this high bar is the common Web browser. but that's not the only client application that can work in this way. any client application written as a state-machine that understands at least one [hyper]media-type can act as a Media Level Model (MLM) client. there are many task-specific "bots" today that act in just this way.
unfortunately, i have not yet found a public Web-based API that uses this model.