Stylesheets for APIs?

[Jørn Wildt]

I just want to share an idea ... what if someone invented a stylesheet/template mechanism for (JSON) APIs? Something like embedding a link to an external template that would be able to transform the API data into something visually appealing. The target audience would be client developers, not end users - and the purpose would be to improve the exploring and learning experience of the API.

By "stylesheet" I think of something like XSLT transformations.

Short example from an issue tracker in HAL:

{

  Title: "Issue 1 - crash on ctrl-p",

  Description: "...",

  Severity: 5,

  _links
  {

    "stylesheet": "http://example.com/api/stylesheets/single-issue"

  }

}

This would allow generic API clients to fetch the stylesheet and render the content to the client developer and thus allow the API developers to "brand" their API and guide new client developers through the API.

This would somehow turn HTML on its head: instead of having a nice HTML presentation with hard-to-locate raw data embedded, we would instead have raw data with with hard-to-locate nice presentation. It would of course require a new type of dedicate generic clients (just like normal browsers are dedicate clients for HTML).

Just a thought. Have a nice day :-)

/Jørn

[Honza Javorek]

Hello,

I think it would be difficult to get internet-wide support for this, but if developers are the intended audience, I think extensions like https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en could fill this gap and maybe they could start to support it somehow.

And, of course, it's something XML already supports for years. The question (for me) is also if we need to make JSON alternatives to every XML technology, or if we should keep JSON as the "less-featured" (but "slim" and "simple, stupid") format and just use XML if we need more features.

Honza

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/groups/opt_out.

[Jørn Wildt]

> And, of course, it's something XML already supports for years. The question (for me) is also if we need to make JSON alternatives to every XML technology,

In this case one could easily transform the JSON to some equivalent XML - and then apply the stylesheet from that. The problem is more that some media types for API's may include actions that are not possible to implement in HTML.

> I think it would be difficult to get internet-wide support for this,

Personally I doubt it too :-) But its an interesting idea (at least I think so).

/Jørn

[Paul Cohen]

Hi,

On Thu, Jan 23, 2014 at 7:49 AM, Jørn Wildt <j...@fjeldgruppen.dk> wrote:

> I just want to share an idea ... what if someone invented a
> stylesheet/template mechanism for (JSON) APIs? Something like embedding a
> link to an external template that would be able to transform the API data
> into something visually appealing.

Why not just support the media type "application/xhtml+xml"? If
someone performs a HTTP GET with Accept: application/xhtml+xml you can
return a XHTML-representation of the resource that is visually
appealing (at least in a web browser that understands it).

I've use this for read-only HTTP API:s and it works fine.

/Paul

--
Paul Cohen
www.seibostudios.se
mobile: +46 730 787 035
e-mail: paul....@seibostudios.se

[Jørn Wildt]

> Why not just support the media type "application/xhtml+xml"?

Because that wouldn't allow the client developers to view the actual API data they are going to work with - they would only be able to browse an HTML version, an equivalent version of course, but still a distraction from the raw data.

Besides that there could be API elements, like hyper media affordances for PUT and DELETE, that HTML cannot handle.

Having said that, I still think HTML versions are a good idea for the tooling we have today.

/Jørn

/Jørn

[Paul Cohen]

Hi

On Thu, Jan 23, 2014 at 2:03 PM, Jørn Wildt <j...@fjeldgruppen.dk> wrote:
>> Why not just support the media type "application/xhtml+xml"?
>
> Because that wouldn't allow the client developers to view the actual API
> data they are going to work with - they would only be able to browse an HTML
> version, an equivalent version of course, but still a distraction from the
> raw data.

I don't understand why the data can't be in the (X)HTML so the
developers can view it. The purpose is simply for the data to be
presented (nicely with CSS) in a browser for developers. This is what
we've done.

[Mike Kelly]

There's so much redundant affordance in HTML if you are building an API... if you have a lot of clients, there's going to be many different ways a client developer could couple code to the DOM structure in order to extract the data, which you could easily break inadvertantly some time in the future.

JSON is popular because it's simple and it has a small footprint, if API adoption is strategically important and you are in a competitive space - HTML is probably not a good choice.

Cheers,

M

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/groups/opt_out.

--
Mike

http://twitter.com/mikekelly85
http://github.com/mikekelly
http://linkedin.com/in/mikekelly123

[Mike Kelly]

Hi Jorn,

are you thinking about this as different to, or beyond, something like the HAL browser?

--

You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/groups/opt_out.

[Jørn Wildt]

> are you thinking about this as different to, or beyond, something like the HAL browser?

Absolutely beyond applications like HAL/Sirene/Other explorers - something like an add-on to them.

/Jørn

[Kevin Swiber]

There was a project long ago named JSONT that aimed to do something similar to this.  Link: http://goessner.net/articles/jsont/

I don't think it was adopted by very many people.

Going with the full power of XSLT for JSON would be a lot more complex.

I definitely agree it's an interesting problem space!  It might be worth prototyping some solutions. 

--
Kevin Swiber

Projects: https://github.com/kevinswiber
Twitter: @kevinswiber

[mca]

i've explored the idea of creating a browser extension for Cj and i think it's got promise.

a client-side explorer ("CjViewer", "SirenViewer", etc.) could display the raw cj and, when users click on links that require arguments, then a popup appears (much like the server-based explorers for HAL and Cj today).

i've also built a couple browser-based js libs for Cj that present a simple HTML UI. this makes it possible to use this single browser app to point to random Cj servers and operate on the data (as long as the server handles the *flippin'* CORS headers).

for at least one XML-based design, i created an XSLT doc for browsers that links to CSS and JS. when the response is sent to a browser "magically" a functional HTML app appears. good news is M2M cases can ignore the XSLT line and the rest of the document is still fully available (w/o any UI annotations).

all good areas that need creative effort, IMO.

mca

+1.859.757.1449
skype:mca.amundsen
http://amundsen.com/blog/
http://twitter.com/mamund
https://github.com/mamund
http://linkedin.com/in/mamund

[snow6oy]

+1 for the idea of browser extensions. Apart from anything such tools would really improve Developer Experience (DX) of using Cj, Siren, HAL ..

[Mike Kelly]

what is the value in a browser extension vs a web app?

--

You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/groups/opt_out.

--

[Steve Klabnik]

You don't need to convince them to let you CORS.

[Glenn Block]

Sounds like an interesting. I don't see how it hurts. If I am a client that understands it then I pull down the stylessheet and can render it, if I don't I just ignore it right?

[Jørn Wildt]

> Sounds like an interesting. I don't see how it hurts. If I am a client that understands it then I pull down the stylessheet and can render it, if I don't I just ignore it right?

Exactly.

/Jørn

[Filip Kolarik]

Hi,

a browser extension can ask for specific permissions (e.g. to allow cross origin requests for XHR). An extension can also get access to various APIs that are not standardized but allows to get some control over some browser, hardware, etc. resources. Here are Chrome Platform APIs as an example:

https://developer.chrome.com/apps/api_index

https://developer.chrome.com/extensions/permissions

Filip

[Mike Kelly]

I definitely prefer the ubiquity/immediacy you get as an API provider
if you go the web app route. You don't need to convince and wait for
your users to download and use a browser extension.

[Jørn Wildt]

> I definitely prefer the ubiquity/immediacy you get as an API provider
> if you go the web app route. You don't need to convince and wait for
> your users to download and use a browser extension.

I just realized the flip-side of this: with a web app you cannot work with services behind a firewall.

/Jørn

[Mike Kelly]

You could deploy the web app inside the firewall, though

[Jørn Wildt]

> You could deploy the web app inside the firewall, though

Sure, but wouldn't it be easier to use a browser extension then?

Oh, well, both have their strong and weak sides.

/Jørn

[Stephen Rylander]

It feels like the stylesheeting of data is rather solved, between XSLT for xml and any of numerous client templating libraries like mustache.  Normally, the whole reason a client wants the data is so they can be de-coupled and format it as they want.

S//R

[Jørn Wildt]

> Normally, the whole reason a client wants the data is so they can be de-coupled and format it as they want.

Correct, but I think you miss my original point: it could be interesting to let the server define the layout when developers are browsing the API data. Just to add some abilities to "brand" the data and maybe format some of it in tables instead of raw JSON. So the server returns both data AND a reference to some external styelsheet/template which the client is supposed to understand and use to render the data in order to improve client developer experience when debugging and exploring the API.

/Jørn

--

You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.

For more options, visit https://groups.google.com/d/optout.

[Darrel Miller]

Jørn,

Personally,  I think the approach you describe is ideal for both developers and end users of hypermedia APIs.  Building "data-first" APIs has been working well for me for the last 8 years.  It's also one of the reasons that I've avoided using the browser as an API client, because

browsers take a fairly myopic view that HTML is the web.

The native clients I build retrieve hypermedia content first and then use a "stylesheet' type of link to discover how to render th atcontent to the user.  I don't use a transform approach Instead the stylesheet has markup to describe the UI and hold fragment identifiers that point into my content representation to enable client side data binding.

There is hope on the horizon for browser.  The ServiceWorker project[1] will allow  responses to be intercepted by JavaScript code to enable the response to be interpreted before anything is rendered.  The script code can follow the stylesheet link and build the HTML UI for rendering. 

I suspect that having this service worker infrastructure will make the SPA approach redundant, as following links to a new page can be intercepted by framework code.

Looking at this "data-first" approach from a historical perspective.  This is how the web and web browsers were designed to work.  HTML was the content (or data) and the browser/CSS decided how to render this this data.  It is only in recent years where developers have mutated HTML to be used only for UI structure that this architecture has been lost.

My 2c,

Darrel

[1 https://github.com/slightlyoff/ServiceWorker

[Austin Wright]

Specification writers who think that HTML is the Web is certainly becoming a problem, I would say the more recent drafts of HTML have become hugely bloated and carry little regard for other DOM serializations or vocabularies, and there's a ton of features that could and should be split off, to the benefit of DOM, XML, and even JSON.

I wouldn't say HTML has been data since the beginning, CSS was only invented in 1997, and Code on Demand was only formalized, as far as I know, with REST in 2000. I put CSS stylesheets in with "Code on Demand" because it instructs the Web browser how to graphically render the HTML - without a default CSS stylesheet, there would be no graphical representation for HTML. For the first decade of the Web, HTML was a language to graphically render a document, not data so much.

I would like to see user-agents that allow browsing other things... Use the HTTP Link header to pass an XSLT document, script, or CSS, to render JSON, for instance. Presently that's only done by constructing a user-agent within a user-agent (an HTML single-page app).

From what you describe, I've had an idea very similar to ServiceWorker, where an adequately described JSON or XML endpoint could be processed and content-negotiated into an HTML endpoint by an intermediate server.

The only downside is this isn't easily done without breaking the RESTful nature of the origin server - the intermediate server would have to mint URIs for the HTML variants of resources, on the same namespace that the origin server uses, likely breaking the opaque nature of URIs.

Austin.

[Darrel Miller]

Austin,

I don't know the history of CSS particularly, but I would assume that
prior to CSS, browsers just had their own internal implementation of
how HTML should be graphically rendered. It wasn't defined in the
HTML spec. And in my opinion, human readable documents are just
another type of data.

The HTML5 specification has the notion of content handler [1] which
allows a browser to delegate the rendering of some unknown media type
to a secondary server. Not sure how well implemented that feature is
though.

Darrel

[1] http://www.whatwg.org/specs/web-apps/current-work/multipage/timers.html#dom-navigator-registercontenthandler

[Stephen M.]

I have been doing some thinking along these lines, and working with a project called Hyperdescribe [1]. It may not exactly be specifying a stylesheet directly for JSON, but it does provide a way to render media types as HTML with stylesheets.

The idea behind it is to allow a way for converting between media types, which makes it possible to convert from a JSON-based media type to others, such as HTML.

Here are some thoughts on how it could be used to accomplish this.

1. On the server, a hypermedia representation is handed off to a Hyperdescribe library that converts it to HTML, which allows for the server to automatically respond to text/html. The developer can then browse the API with their browser. This of course does not allow for some HTTP support without some extra Javascript.

2. A generic app could be created that grabs the representation and displays its components in HTML (or whatever). The app would handle the links and form submits, allowing for support of PUT, DELETE, etc. This would be a kind of generic HAL browser that could allow for browsing any supported hypermedia type.

3. I use Postman [2] for some things, and it would neat to have some of this stuff built in to existing clients like it to make it understand a bunch of hypermedia types. It could be used to make Postman aware of links and other actions in hypermedia messages, so you could actually click the links in the JSON respones, or make a browseable HTML version in side a panel.

4. A HTTP header link could be used to link to a Javascript browser. The HTML could be Javascript templates that just needs a place to mount.

This is all thinking out loud. I'm still working through Hyperdescribe at this point, but once it gets to a good point, I'm going to start playing with converting media types to HTML. I've started some initial work on a library for handling this in Javascript called Halpert [3].

Just some thoughts!

[1] https://github.com/smizell/hyperdescribe/blob/master/hyperdescribe-draft.md

[2] http://www.getpostman.com/

[3] https://github.com/smizell/halpert