uHateoas

uHateoas

HYPERMEDIA AS THE ENGINE OF APPLICATION STATE FOR UMBRACO

Learn more
How to use uHateoas?

Learn more

What is HATEOAS ?

HATEOAS, an abbreviation for Hypermedia as the Engine of Application State, is a constraint of the REST application architecture that distinguishes it from most other network application architectures. The principle is that a client interacts with a network application entirely through hypermedia provided dynamically by application servers.

A REST client needs no prior knowledge about how to interact with any particular application or server beyond a generic understanding of hypermedia. By contrast, in a service-oriented architecture (SOA), clients and servers interact through a fixed interface shared through documentation or an interface description language (IDL). The HATEOAS constraint decouples client and server in a way that allows the server functionality to evolve independently.

What is UHATEOAS and why should we care ?

Umbraco REST Hypermedia API - Umbraco Hypermedia As The Engine Of Application State

We all love using Umbraco to build our websites, web & mobile apps, but not all of us have C# skills. Umbraco & uHateoas provide us with an intuitive web based UI to define, capture and maintain entities, relationships and rules for our content in an intuitive non technical interface, now coupled with a queryable, updatable Hypermedia REST API.

When it comes to taking our content and using it on websites, mobile hybrid apps or anywhere you can dream of, it assumes a certain level of understanding of the ASP.NET stack, Webforms, MVC, Razor, Web API etc.

Check out the repo on GitHub : https://github.com/League-Digital/uhateoas

This is not a problem for any ASP.NET developer, but what about someone that is great at HTML, CSS and Javascript and doesn't know or care about ASP.NET?

At the moment you would need a ASP.NET developer to expose selected functionality and data via a custom written Web API, that would expose certain parts of the data stored in Umbraco.

This could then be consumed by the front-end developer via the custom REST based API that the ASP.NET developer produced.

With UHATEOAS, this is not necessary.

Simply install the UHATEOAS package and your Umbraco content is now automatically discoverable, navigable, query-able, page-able and editable via a standard Hypermedia API that is driven by the Document Types, DataTypes, Structure, Rules and User / Member Access Control that you define through the Umbraco Back-Office.

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.

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 web-site, i.e. the starting URL. If you want access to all the content, start at the root of your web-site, if not, specify a more specific URL. Unlike most API's, you don't need to know or be told to use a specific API endpoint, you simply use the one you already know from surfing your web-site!

Querying Umbraco

This is where the API really shines. It can be used to query, segment, filter and page your content in a SQL/LINQ like way using simple name-value pair switches. These name/value pairs should be recognised by the average Umbraco developer, as they are concepts that you use every day when building sites using Razor. Now you can just use them directly via the URL as a set of URL based parameters!

Editing Umbraco

The POST , PUT, PATCH and DELETE verbs allow you to do Create Update and Delete operations using IContent via the Content Service when logged in as an Umbraco Back-Office User.

The API exposes Actions based on the permissions of the logged-in Umbraco User.

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.

End-Point Url:

http://uhateoas.league.co.za/

Descendants:

Select:

Children:

Where:

Skip:

Take:

Resolve Media:

Resolve Content:

Html:

Content-Type:

Get in touch about uHateoas

Thanks for your interest in uHateoas

Sending your message...

Thanks! we'll get back to you soon.

Created and designed by WG2K.com
With help from Umbraco

How to use uHateoas?