The REST architectural style has a 'Code on Demand' optional constraint.
here in Fielding's thesis, also
here. Also see
this observation from Joe Gregorio.
Excerpt: "In the code-on-demand style, a client component has access to a set of resources, but not the know-how on how to process them. It sends a request to a remote server for the code representing that know-how, receives that code, and executes
it locally." (Roy Fielding)
Let us consider a REST service that exposes resource representations in JSON, based on one or more private media types; i.e. media types that are introduced by that service. The
Sun Cloud API is a good example of this. But it could just as well be your REST service, and mine too. Clients have access to a set of resources, and they
do have the know-how to process them, because the media types are all (hopefully) well documented.
However, for any one REST service, there are N clients of that service. The service provider hopes for a high N value, as high as possible. But as N increases, so too does the chance of a client misinterpreting the semantics of a media type.
The chance increases (e.g.) that a client will hardcode a server-generated URI that should not be hardcoded. Plus if all those N clients have to separately interpret and parse and correctly interoperate with each media type - that's a lot of duplicated
What if the service did that work? What if the service were to write a code-on-demand, per-media type, downloadable script - available to any/all clients - that correctly interpreted resource respresentations based on that media type? The script
would does its work in the service-approved way. Plus it would evolve as the schema for the media type's JSON evolved over time (hopefully maintaining backward compatibility). This takes a load of work off all those clients, and helps ensure that
clients get implemented correctly. It reduces the amount of time and brain power that each client implementor would otherwise have to expend parsing each media type's written documentation.
to process a specific media type.
Now I'll give an example of my use case from my own REST service:- The top-level "Service" resource indicates whether the user in question has or has not accepted the latest EULA. If they have, then the number of (financial) portfolios owned
by the user is given. A hypermedia control to the EULA resource is always given. A hypermedia control to the user's collection of portfolios is given, but only if he/she has accepted the EULA.
is called "Service". The ctor function takes the complete JSON message body (aka resource representation) as an arg, and initialises itself with that. The ctor function has functions attached to its prototype (i.e. methods) that expose in programmatic
- gets flag saying whether the user has accepted the EULA or not
- gets the total number of portfolios that the user owns (returns null if user hasn't accepted EULA)
- gets URI of the EULA resource
- gets URI of the portfolios collection resource (returns null if user hasn't accepted EULA)
One final thing: even if a REST client wasn't able to execute a c-o-d "media type processor" script, it would still be wise for the REST service implementor to write such a script, and make it available as an intrinsic part of a media type's documentation.
I.e. it would provide a reference implementation that client authors could translate into their own terms: C#, VB, Java, Ruby, whatever.