Code on Demand: What is it

I don't really know

Let me start with full disclosure: I don't really know what Code on Demand (CoD) is. I know it's part of the HATEOAS, or REST ideal (See Fielding Dissertation

I know that CoD means providing code which can be used for interpreting or using an API endpoint. This is an interesting topic, considering my current predicament. I need to add stripe payments to my very flexible HATEOAS Javascript client.

My client is exceptionally generic and abstract, rendering standard JSON Hyper Schema APIs into user friendly websites. It would be a shame to "hard code" Stripe into my client. I need code on demand!

Let's examine the typical use of Code on Demand for taking stripe payments.

Stripe offers code on demand

Stripe offers their own code on demand:

This checkout.js offers all the functionality needed to take a payment via stripe on your website. That's great. That's code on demand, but it still requires hard coding the above form into your HTML pages. In a way, it's like any other Javascript file being included....until, that is, it's loaded BECAUSE the API schema semantics told the client application to load it. HTML does this. Essentially, we could argue that HTML is application code, and that the HTML returned from a server endpoint is much like an API returning an HTML media content type, which in turn tells the browser to load some code on demand. Essentially, Stripe form is CoD.

An Even More Dynamic Code on Demand

What if an API client could load code on demand in the same way? Perhaps a semantic link returned within the schema for an endpoint could be interpreted by the client application to then load and instantiate the code on demand. That would mean that my client could interpret some semantic link as a command to load some arbitrary Script and then run it. Sounds interesting, easy to do and flexible. Yeah, there are security concerns, but that's what Cross Server Scripting restrictions were made for.

Many bloggers write about the CoD constraint of REST. It's a curious requirement, but at the same time the CoD constraint is one of the things that makes the web so amazing. I recall speaking with a Netflix engineer as they were converting all their embedded Java and C+ into Javascript so that they could easily update their client side code: on demand.

Start with the API Relation Semantic

My CoD is going come in the form of a link. I need to choose a semantic to represent to the client that this link should be treated as CoD. My API will return it in the schema along side the data for an endpoint. My client application will then interpret that link and load the script. Which relation type would this be? I can't seem to find a good one. I perused for ideas, but alas, it seems HTTP doesn't treat CoD as a relation.

It's not clear. It seems like the HTTP standard did not contemplate having a CoD link relation type. They did include a stylesheet relation....odd? The Chromium project mentions a "subresource" relation: It seems like what I want.

Seems someone agrees with me that most APIs never intended for CoD to be used.

Even the most by-the-book Hypermedia APIs currently send
completely static content to the client. They do achieve one level of de-coupling by communicating controls in the response message, through link relations, but the communication is still limited to the semantics of the media type that the client knows beforehand and which would have to had been hard-coded in its implementation.

Case in point: media types can be extended with custom profiles but clients have little ability to do much interesting with the extended semantics unless they understand it beforehand. Servers are currently unable to send code leveraging the additional semantics, in the response message. This limitation obviously leads to some level of tight-coupling of server logic with client code that may be critical in certain scenarios.


Moving Past Semantics

I'll get past the semantics by choosing something serviceable. Yeah, it won't be in th JSON Hyper Schema RFC, and it won't be standard, but it will accomplish what I need.