View all posts

Hypermedia client - details

This is a serie about developing a simple Hypermedia Client in AngularJS.

  1. Hypermedia introduction
  2. Hypermedia formats
  3. Hypermedia client
  4. Considerations
  5. Hypermedia does not replace your semantic model

In this post I am going to review fundamental parts of angular js client. You may be not interested at all if you dislike Angular, or if you just like to read theory and not see the practise (as 90% of Hypermedia speakers, see this guy or this other one, for example.).

So, first things first. Why do not embrace Angular 2? To be honest, I’ve been tempted until the last moment to use the new framework, but after couple of hours I decided to revert back to Angular 1 for the following reason.

  1. When the project started (26/02/2015), Angular was not even in alpha state, not present on Npm.

  2. Even if not it is present on npm, it still has not got a main entry into package.json file, that makes everything a bit more difficult

  3. jspm lacks support, actually, to transpile everything that is not es6 (but .ts native support is coming). If I’ve to use angular2, I want to use Typescript.

  4. Using angular2 would mean starting literally from 0, while with angular 1.x you have got an huge library of resources, directives, reads and so on.

  5. While I totally disagree with this very common sentence “Angular 2 is a completely new framework”, I still belive that the transition to that framework would not be totally painless. The aim of the project was to evaluate the difficutiles about writing an hypermedia client, not evaluating the framework itself. For this reason, I thought that starting with something I was comfortable with would be a more fair point.

So, Angular 1, no more doubts about that.

Package manager

The first one was, of course, Bower. There is a very huge debate about “Where should I publish my browser package?” Bower? Npm? Download the file as a GitHub release? And after? Browserify? Webpack?

Several months ago I was having a look at Aurelia framework, and I literally falled in love for jspm. Basically it is a module-loader + package manager + build tool + transpiler (ES7 as well using babel)for modern web applications. It supports plugins (to load something more than just javascript files), github, npm, bower or what you want as source for packages. Furthermore, it leverages SystemJS as module loader.

Minuses? From my point of view, just a big one: since Aurelia is their “bigger customer”, they cannot move forward until that framework is ready. This could be quite annoying, expecially when important bugs are discovered.

As second niptick, there are not so many plugins as Webpack, but it is something that I am quite confident it will definitely improve (given that SystemJS should became the new standard, I guess).

The Hypermedia Client

Writing a client from scratch was out of question. I don’t think I have got the capabilities to make a decent one (at least, not yet). Given that, I had to find one that could be suitable for me.

This was not an easy choice. The first thing that you would probably do is to search something like Hypermedia client angularjs on Google, and that is what basically I did. There are several good clients such as Hyperagent or Angular-hateoas, but the one that caught my attention was angular-hy-res.

To be honest, I do not remember how I found that, but I am sure what made me choose it.

  1. It is just a thin layer on top of hy-res library, written and mantained by the same author.
  2. Support for multiple mediatype formats (CJ, Siren and HAL, actually). Thanks to the plugin structure, add new adapters should be really really easy.
  3. Awesome person behind it. Albeit the library was not complete, I filed several issues and pull requestes that were handled, honestly, in a very professional manner and at speed of light.

Generating the forms

One of the most interesting parts of Siren is the action concept, that basically is the fill the form part of browser counterpart. So, we do have an array of siren fields in a action context, how can we render them?

Of course, we can hardcode them by hand, but after a while I found a very interesting project that was aiming to solve this problem: angular-formly. With few lines of code I was able to create custom templates based on Siren field name.

After that, given that Siren actions are kind of standard, I’ve started a collaboration with the team to create a siren adapter for angular-formly. I really hope to start to contribute as soon as possible.

Want to know more?

Feel free to file an issue or write me an email! I’d be happy to give you further details!

What’s left?

There is still a lot of work, but the client definitely works!

Last sweet thing. During the time, I’ve been tracking on a personal Trello card all the issues I found, and if they were resolved. Are you curious about that? Here is the list!


  1. pollsApi does not support CORS headers
  2. angular-hy-res does not support header parameters
  3. jspm bower endpoint cannot update a library.
  4. angular-hy-res forgets about the given host when issuing following requests
  5. angular-hy-res does not support Siren actions
  6. restangular requires lodash as a global object
  7. pollsApi does not paginate the returned data.
  8. multiple entries into bower file endpoint
  9. multiple entries for jspm cli bower file
  10. ombnibar override in jspm
  11. angular-hy-res cannot give me list of actions in Siren
  12. ng-promise-status cannot be installed as a npm module
  13. pollsApi does not fill siren fields appropriately.
  14. Siren form type is not filled
  15. jspm-cli omits the polyfill for Internet Explorer
  16. hy res promises are not rejected when an error happens

Nice to have

  1. Http batching support for polls api
  2. Reset Polls api contents periodically
  3. angular-hy-res module name from Batarang
  4. angular-hy-res should provide an unwrap method
  5. angular-hy-res on Npm registry
  6. svg progress bar linear. Won’t be implemented, found another one.
  7. omibar as npm package
  8. Siren action support for angular-formly
  9. pollsApi order polls by publish date
  10. jspm does not support other than simply css loader
  11. ngPromiseStatus places a completely wrong condition
  12. pollsApi is missing First link in pagination
  13. pollsApi is missing template URLs for the pages
  14. angular hy res does not work in strictly DI

Yeah, programming is easy, they said.