uHateoas - Umbraco Hypermedia As The Engine Of Application State

Umbraco REST Hypermedia API.

We all love using Umbraco to build our websites, web & mobile apps, but not everyone has 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.

Project Site : https://uhateoas.leaguedigital.com/
GitHub : https://github.com/uhateoas/uhateoas

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. 

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. 

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 taken off! 

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 UHATEOAS 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. Please Note : PUT, PATCH and DELETE verb support has only been enabled in version 1.3.2.

The actions Create, Update and Delete are exposed as a collection of actions based on the User's admin rights and the DocumentTypes that are allowed under the current node. With the Umbraco Hypermedia API, you are able to create complex Single Page Applications without writing a single line of server-side code. It turns any Umbraco v7+ website into a REST based data repository with a very capable, query-able Hypermedia API!

We are working on a build where you will be able to map Umbraco Member roles to Umbraco Users as well as mapping anonymous visitors to an anonymous Umbraco User to facilitate creation of nodes for use cases like ContactUs, Comment etc where we would like to enable visitors that are not logged in to be able to use the POST and PATCH verbs in a controlled manner.