hyped

hyped

A simple approach to generating HAL-esque hypermedia responses based on resource definitions. Built to work best with autohost but should work with most Node.JS HTTP stacks with a little extra effort.

This is alphaware!

Concepts

You can skip to the Using section but understanding the concepts behind should explain

Resource Definition

The resource definition provides the metadata necessary for hyped to generate the hypermedia based on the model you provide it. This declaritive approach takes advantage of the structure and property names you provide to make implicit associations. The trade-off is that the associations are made based on consistent naming across several properties and values and typos will break the expected outcome.

Notes

1. include and exclude are mutually exclusive

1. Properties listed in embed are not included in the response body. To override this, you'll need to list them in the include array.

{
	[resourceName]: the resource name (must be unique)
	parent: (optional) the name of the resource that this "belongs" to.
	actions: {
		[actionName]: {
			method: the http verb/method
			url: the URL for this action
			include: property names array to include in the rendered response
			exclude: property names array to exclude from rendered response
			filter: predicate to determine if a property's key/value should be included
			condition: returns true if the action is valid for the given model
			embed: defines which model properties are embedded resources and how to render them
			links: provides alternate/compatible urls for activating this action
		}
	},
	versions: {
		#: {
			[actionName]: {
				// provide any of the above properties to change how this
				// version will differ from the previous version
				// these changes are applied cumulatively in descending order
			}
		}
	}
}

// an embed section looks like this:
{
	[propertyName]: {
		resource: name of the embedded resource
		render: which action will be used to render the resource (usually "self")
		actions: an array of the actions that should be included
	}
}

// a link section looks like this:
{
	[actionName]: url|generator
}

Resource Fields

resourceName

The name of your resource. This will be important to keep unique and easy to remember because the parent property of other resources and the resource property of an embed section will need to match one of your resource names.

parent

Defines this resource as belonging to another resource. This will cause all of the action URLs in this resource to be prefixed by the parent resource's self href.

actionName

The name of the action will determine the name of the link exposed in the resource's links.

method

The HTTP method used to activate this action.

url

The URL segment for this action. If there is no parent resource, this will be the URL for this action. If a parent resource has been specified, the parent's self URL will get pre-pended to the URL provided here.

include

A list of properties to include from the raw data model in the response.

exclude

A list of properties to exclude from the raw data model in the response.

filter

A function to determine which data model keys shouldn't be included in the response.

transform

A way to perform a map function against the model to produce the response body.

condition

A predicate used to determine if this action should be included in the link list when rendering a response.

embed

This section defines whether or not other resources can/should be included in the action's response. It effectively allows the server to provide pre-fetched, related resources to the client.

embed - propertyName

The name of the property on the data model that will contain one or more of the embedded resources. This property name will, by default, be removed from the response.

embed - resource

The name of the resource that defines how each item under the data model property should be rendered as a resource.

embed - render

Determines which of the embedded resource's actions should be used to produce its representation as an embedded resource.

embed - actions

A string array listing which links should be provided per embedded resource.

links

A hash of additional actions to include in the links related to this action. These additional links will only be included in a resource's `_links` when the action itself is valid (passes both auth and `condition` checks when provided). Note - you cannot provide a method other than what already exists on the action the links belong to (it wouldn't make sense).

This feature is to allow action aliases for known sets of query parameters.
</dd>
<dt>links - url</dt>
<dd>Works the same as the `url` for the action.</dd>
<dt>links - generator</dt>
<dd>A function that takes the data model and a context hash and optionally returns a url string. Returning an empty string or undefined will exclude the link from rendered results. See <a href="#rendering-api">Rendering API</a> for how the context is specified.
<div class="highlight highlight-javascript">	<pre>
"next-page": function( data, context ) {
	// results in a url like "/thing?page=1&amp;size=10"
	return "/thing?page=" + ( context.page + 1 ) + "&amp;size=" + context.size;
}
</pre>
</div>
</dd>

Example

// account resource
{
	name: "account",
	actions: {
		self: {
			method: "get",
			url: "/account/:id",
			include: [ "id", "balance" ],
			embed: {
				transactions: {
					resource: "transaction",
					render: "self",
					actions: [ "self", "detail" ]
				}
			}
		},
		withdraw: {
			method: "POST",
			url: "/account/:id/withdrawal",
			condition: function( account ) {
				return account.balance > 0;
			},
			include: [ "id", "accountId", "amount", "balance", "newBalance" ]
		},
		deposit: {
			method: "POST",
			url: "/account/:id/deposit",
			include: [ "id", "accountId", "amount", "balance", "newBalance" ]
		}
	}
}

//transaction resource
{
	name: "transaction",
	parent: "account",
	actions: {
		self: {
			method: "get",
			url: "/transaction/:transaction.id",
			include: [ "id", "amount", "date" ],
			links: {
				"details": "/transaction/:transaction.id?detail=true"
			}
		}
	}
}

Rendering

hyped generates an abstract hypermedia model based off a resource definition and data model. This hypermedia model is then passed to a "rendering engine" that produces a HTTP response body based on the requested media type.

Abstract hypermedia model

Understanding the structure of the hypermedia model is important if you'd like to define your own rendering function for custom media types.

HyperModel Structure

{
	// top level properties starting with a '_' are metadata
	// all other properties are attached based on the resource definition
	_origin: { href: "", method: "" },
	_links: {
		self: { href: "/thing/100", method: "get" },
		child: { href: "/thing/100/child/:childId", method: "get", templated: true }
	},
	_embedded: {
		children: [
			// each embedded resource will follow the same pattern/format
		]
	}
}

_origin

The origin provides the method and href that you would use to get to the current result. _origin is repeated even for embedded resources so that the consumer can tell how they would get to the same representation that was included in the embedded section.

<dt>_links</dt>
<dd>The actions available for the given resource.</dd>

<dt>_embedded</dt>
<dd>If a key in the <tt>embed</tt> section matches one on the data model provided, the resources contained will show up under the property matching the one on the data model. Each embedded resource will contain <tt>_origin</tt> and <tt>_links</tt> and may also include its own <tt>_embedded</tt> section.</dd>

Rendering engine

Rendering engines are simply functions with the signature function( hyperModel ). These functions take the hyperModel and produce the correct response body for their given media type. The built in engine for "application/hal+json" looks like this:

function render( model ) { 
	return JSON.stringify( model );
}

Note: the engine for "application/json" is more complex since it has to effectively reduce and filter a more complex data structure to produce simple JSON.

Content negotiation

The accept header is used to select an appropriate rendering engine (if one is available). If no engine matches the provided media type, hyped will respond to the client request with a 415 explaining that the requested media type is not supported.

Versioning

New versions are implemented as diffs that get applied, in order, against the baseline. Each version provides new values for properties that replace parts of the metadata for the resource. This will hopefully make it easy to see the differences between versions of a resource and reduce the amount of copy/pasted code between versions of a resource definition.

URLs

hyped will attempt to replace path variables specified in two separate styles for two separate use cases:

Express style variables

1. :property
2. :property.childProperty

Brace style variables

1. {property}
2. {property.childProperty}

Either style is valid when specifying the URL in the action, hyped will make sure that the correct form is used (Express style gets used server side for assigning routes while brace style is returned in all client responses).

The first form will be used to attempt to read a property directly on the model. The second will attempt to read a nested property or a property name that combines the two in camel-case fahsion (i.e. propertyChildProperty). In either case, if no match is found, the variable will be left in tact. In the second case, the period is removed and the variable becomes camel-case.

Example:

{
	name: "user",
	actions: {
		self: {
			method: "get",
			url: "/user/:user.name"
		}
	}
}

If the user model in question had a name property of "leroyJenkins", the response body would look like this:

{
	"name": "leroyJenkins",
	"_links": {
		"self": { "href": "/user/leroyJenkins", "method": "GET" }
	}
}

When a URL contains path variables that could not be replaced by a value in the model, the action/origin link will indicated this with a templated property set to true.

Note: the client will always see brace-style path variables

{
	"name": "leroyJenkins",
	"_links": {
		"self": { "href": "/user/leroyJenkins", "verb": "GET" },
		"insult": { "href": "/user/leroyJenkins/{insult}", "verb": "POST", "templated": true }
	}
}

Usage

These examples show the bare minimum. You'll only get support for built in mediatypes - presently application/json and application/hal+json. This means if you don't provide your own engine for custom media types and a client sends an accept header for a media type hyped knows about, it will send back a 415 (unsupported media type) to the client rather than throwing an exception.

With Autohost

This example will add an express middleware to autohost that extends the envelope with a fluent set of calls that can be used to construct and render a hypermedia response. The correct version, rendering engine, resource and action are all determined during the hyped middleware you add to autohost so that when rendering a response, the only things you must provide is the model.

Note: at this time autohost 0.3.0-3 or greater is required

index.js

var autohost = require( "autohost" );
var hyped = require( "hyped" )();
autohost
	.init( {
		noOptions: true, // turn off autohost's OPTIONS middleware
		urlStrategy: hyped.urlStrategy // use hyped's URL strategy
	} )
	.then( hyped.addResources );
hyped.setupMiddleware( autohost );

resource.js

var databass = require( "myDAL" );
module.exports = {
	name: "something",
	actions: {
		self: {
			method: "get",
			url: "/something/:id",
			exclude: [],
			handle: function( envelope ) {
				var model = databass.getSomethingById( id );
				envelope.hyped( model ).status( 200 ).render();
			}
		}
	},
	versions: {
		2: {
			exlude: [ "weirdFieldWeShouldNotExpose" ]
		}
	}
};

With Express

express

// assumes you have a hash containing all your resource definitions and express set up
var hyped = require( "hyped" )( resources );
hyped.setupMiddleware( app );

app.get( "something/:id", function( req, res ) {
	var id = req.param( "id" );
	var model = databass.getSomethingById( id );
	req.hyped( model ).resource( "something" ).action( "self" ).status( 200 ).render();
} );

API

If you are using this library with Autohost, the only API you really need to know about is used for the initial setup and the response generation.

Setup API

addResource( resource, resourceName )

Adds the metadata for a particular resource.

addResources( resources )

Adds multiple resources at once. Intended to make autohost setup simple.

autohost.init( { noOptions: true } )
	.then( hyped.addResources );

registerEngine( mediaType, renderer )

Registers a rendering function with one or more mediaTypes.

// this is a ridiculous example. don't do it.
hyped.registerEngine( "text/plain", function( model ) {
	return model.toString();
} );

setupMiddleware( server )

This call can take either a reference to the autohost lib or express's app instance. It will register both the hypermediaMiddleware and the optionsMiddleware with the HTTP library in use.

Refer to the usage examples above to see this call in use.

versionWith( versionFn )

Changes hyped's default versioning detection approach. This is experimental and not recommended. The versionFn is a function that takes the request object and returns a version number.

// this isn't great, but if you have to ...
hyped.versionWith( req ) {
	return req.headers[ "x-version" ] || 1;
}

Rendering API

The hypermedia middleware extends autohost's envelope and the underlying request object with a set of fluent calls to help with the construction of a hypermedia response.

Keep in mind that normally, you will only use the hyped, status and render calls. The middleware should correctly detect the version, mediatype, resource and action to be rendered.

	// within an autohost handler
	envelope.hyped( myData ).status( 200 ).render();
	
	// within an express route
	req.hyped( myData ).status( 200 ).render();

.hyped( model, [context] )

You provide the data model that the resource will render a response based on. The resources are designed to work with models that may have a great deal more information than should ever be exposed to the client.

.resource( resourceName )

When the resource that needs to be rendered is not the one the action is contained within.

.action( actionName )

When the action you want rendered is not the one being activated.

.context( context )

Another way to provide context to any link generators for this action.

.status( statusCode )

If omitted, this is always 200. Be good to your API's consumers and use proper status codes.

.render()

Returns the response to the client.

Departures/Extensions To HAL

I think HAL is pretty awesome. We"ve added a few minor extensions and may continue. This is where we"ll describe them.

Options

_versions and _mediatypes properties have been added to the payload returned from the OPTIONS call to the API root. They will list the available versions and mediatypes currently supported by the server.

OPTIONS response structure

{
	"_links": {
		"resource:action": { href: "", method: "", templated: true }
	}
}

All actions will be returned under the top-level _links property. The action names returned from OPTIONS will be namespaced by the resource name delimited by a colon.

Origin

Provides a data structure identical to the link that would be called to produce the response. This is especially useful within embedded resources as it allows the client to see what link action was used to produce the embedded resource included in the payload.

We added this to make it easier for clients to know which representation they have in memory for the sake of both local caching and requesting updated versions. We recommend including etag or last-modified data along with resources to further improve efficiency.

Links

Methods

HAL does not include the HTTP verb/method used for an link"s href. Our version does include this information in the link using the verb property. As in our URL example from above:

{
	"name": "leroyJenkins",
	"_links": {
		"self": { "href": "/user/leroyJenkins", "verb": "GET" }
	}
}

Contributing

The tests are a bit of a contrived mess at the moment but do exercise the features and known use cases. If submitting a PR, please do the following:

• Branch for the feature/fix
• Make any changes to the README required to reflect changes
• Create/modify tests

Roadmap

None of this is guaranteed but here are some items that would be nice/great to have.

• Add extension to hypermedia for describing query parameters
• Add ability to define data contracts for request/response bodies per resource and action
• Filter options response based on authorization method
• Support for websockets

Changelog

0.0.11

• Support the ability to include additional links per action
• Allow the render to specify the origin instead of calculating it
• Bug fix - missing embedded properties should not cause the world to end