web.rest.design - grecosoft/NetFusion GitHub Wiki

REST/HAL Plugin Component Design

The following describes the main classes from which the NetFusion REST/HAL plugin and related assemblies are comprised. This plugin provides an easy way to describe resource related links that can be easily discovered by the API consumer. These links, based on the simple HAL protocol, allow the consumer to take actions on the resource and navigate to other related resources. This plugin defines classes allowing resource URLs to be specified with expressions and not hard-coded strings.

Resource based links allow for a REST API to be easily discovered. This allows developers programming against the API, such as for a Web client, to easily know the URLs to be invoked without having to refer the server-side code.

The HAL protocol also allows for embedded resources. Instead of returning an object model with static properties referencing associated data, additional related resources is embedded into the returned resource. This allows for the resource structure to easily adapt to change. Also, the consumer can specify which embedded resources to load allowing the amount of data transferred based on the client. For example, a mobile application my want to only load a subset of the initial available embedded resources and navigate to the other resources only when needed.

An embedded resource is like any other resource (a JSON object with properties and a set of related links) but is embedded into another related resource. Also, an embedded resource can be a collection of resources.

The following link provides more details about the HAL specification.

ResourceMediaModule

Responsible for discovering the IResourceMap instances declared by other plugins (most often by the Host plugin).

IResourceMap

Used to define the REST/HAL links associated with a set of resources. These mappings are most often defined within an ASP.NET Core WebApi assembly. A mapping contains a set of IResourceMeta references each describing a resource type's associated links.

ResourceMap

Abstract base class implementing the IResourceMap interface and maintains a set of related IResourceMeta derived class instances.

HalResourceMap

Derives from ResourceMap and provides a factory method used to create an instance of the HalResourceMeta class for a specified resource type. The created instances are added to the collection of IResourceMeta objects managed by the base ResourceMap class. The returned HalResourceMeta provides a fluent, type-save, API for defining a resource's associated links.

IResourceMeta

Represents metadata for a set of links associated with a specific IResource type. Contains a collection of ResourceLink instances. Each item in the collection contains the metadata needed to generate a link at runtime.

ResourceMeta

An implementation of IResourceMeta providing expression based methods used to specify metadata for different styles of links. Based on the type of link created, an instance the the ResourceLink, or one of its derived classes, is added to the collection of links. The following link styles are supported:

Controller/Resource: This type of link is based on the selection of a controller's method. An expression is used to select the controller's route. At runtime, the corresponding URL is generated using ASP.NET Core's UrlBuild class. The resource properties, specified for each route method parameter, are used to determine the route parameter URL values at runtime based on the returned resource instance. The following is an example:
```
.LinkMeta<LinkedResourceController>(
	meta => meta.Url("car-details", (c, r) => c.GetByIdAndRequiredParam(r.Make, r.Model)));
```
Templated Based: Where the prior type of URL is a complete URL without and token placeholders, a template based URL contains placeholders to be specified by the calling client.
Resource Interpolated URL: This type of URL can be used to specify an external URL since the corresponding controller would be in another WebApi project. The following is such an example:
```
resource => $"http://services.customer/{resource.CustomerId}"
```
Hard-Coded URL: This is the most simple but the hardest to maintain. This is a fully specified URL to an external resource.

HALResourceMeta

Derives form ResourceMeta and allows for the definition of HAL specific metadata methods. Currently this class is empty but provided for a well balanced design.

MediaTypeEntry

When the ResourceMediaModule is bootstrapped, it locates all IResourceMap instances. Each mapping has an associated media-type. In the case of HAL, it is application/hal+json and is currently supported by the REST plugin. A dictionary keyed by media-type is maintained by the ResourceMediaModule. For each media-type, the dictionary stores an instance of MediaTypeEntry. Each entry instance has a collection of IResourceMedia class instances where each one describes the metadata for a specific resource type for that associated media-type.

IResourceProvider

When a resource is requested for a specific media-type, the MediaTypeEntry's associated IResourceProvider is used to apply the links, based on the resource's defined link metadata, to the returned IResource instance.

ResourceProvider

Provides a default implementation of IResourceProvider that generates a resource's links based on its associated metadata for the requested media-type.

HalResourceProvider

Derives from ResourceProvider and allows for the applying of HAL specific features to returned resources. Currently this class is empty but provides for a well balanced design.

HalFormatter

HAL specific implementation of the base ASP.NET Core IOutputFormatter and IApiResponseTypeMetadataProvider interfaces. The HalFormatter is invoked when the request's Accept header value is application/hal+json. The implementation applies links to all embedded resources and resource collections. The IResourceMediaModule is invoked for each returned resource specifying the HAL meta-type. The IResourceMediaModule implementation locates the MetaTypeEntry associated with the passed media-type (hal+json in this case) and calls the associated IResourceProvider on the resource.

IHalEmbeddedResourceContext

A service that can be injected into any application component to determine the embedded resources requested by the client. The client requests a subset of embedded resources by adding the embed query string parameter. The value is a comma delimited list of keys used to identify each type of embedded resource to be returned. If the request does not specify the embed URL, it is assumed that all resources should be returned.

RestModule

Plugin module registering needed ASP.NET Core services needed for route URL generation. Also adds the HalFormatter to the ASP.NET options.