Getting Started

Installation

Simply install the uHateoas package from the Project's section on Our Umbraco

That's it, you are ready to rock! You are now able to query your Umbraco website using any REST client i.e. Advanced REST Client, Postman, Paw, Insomnia and of course via JavaScript using any of the JavaScript library's out there like jQuery, AngularJS, Polymer, Knockout, React etc.

Content-Type Request Headers

We wanted the uHateoas API to be intuitive and easy to use ideally without any prior experience and with minimal or no documentation. That sounds typical of a lazy developer speaking, but Hypermedia As The Engine Of Application State really does deliver in this regard. Think of a website with lots of pages, with lots of relevant information, but with no hyper-links and no forms for accepting feedback. The web would never have got off the ground!

So why make API's black boxes that need documentation just in order to use them? Why not simply surf to the web-site and specify the Content-Type Header that you would like to get the web-site's data returned to you in! By default if you don't specify a Content-Type Header, as you would expect you will simply get back HTML. If however you specify a different Content-Type Header instead of the default text/html, wouldn't it be great to get back the raw data of that resource in the format that you want it?

This means that any page on your Umbraco web-site can now be served up in whatever format you support, via the URL that you would normally use on the web-site, simply by changing the Content-Type Header in the request.

The uHateoas API is designed to give RESTful clients access to the data stored as IPublishedContent in a typical Umbraco web site via the Content Service in a number of supported data formats i.e. json, xml, umbraco+json or any of the HATEOAS hypermedia formats ( hal, collection-json, siren etc... ) that you can implement via a simple Umbraco alternate template. The HATEOAS formats, specifically umbraco+json makes your entire Umbraco Content tree discoverable and navigable via the json link collections. The links are filtered based on membership access and only expose Published Content.

Three alternate templates are supplied with the package as a starting point, feel free to add your own and contribute back to the project:

  • umbraco+json - An umbraco centric Hypermedia format based on Siren and Magic Hypermedia (Thanks Amith & Team)
  • json - A basic json format without the Hypermedia Links and Actions
  • xml - An xml representation of the json format.

By default these three templates are associated with Content-Type headers that are configurable via the web.config and are integrated into the Umbraco Request Pipeline, so that if you supply the appropriate Content-Type header, the resource that you are asking for will be returned in that format without specifying the alternate template. For most developers, this would be the natural way of requesting the data.

Content-Type templates ( web.config )

Adding additional views/templates can be done simply by adding a new setting to appSettings for example :

<add key="WG2K.Hypermedia.Templates.text/rss+xml" value="urss" />

The uhateoas.cshtml view/template

The ujson.cshtml view/template

The uxml.cshtml view/template

uHateoas Playground

This is the uHateoas Playground. It is an URL Hypermedia Query Builder that allows you to experiment and discover the data in our demo site, and we have made it available for you to use to build up queries on your site too, if you install the Package. The playground is available on every page of your website by simply adding "/ueditor" to the end of your website url.

http://uhateoas.league.co.za/getting-started/





General Usage

As mentioned if you specify a Content-Type such as text/umbraco+json or text/json or text/xml, then all you need is to supply the starting point in your w...

Learn more

Created and designed by WG2K.com
With help from Umbraco

Back to top