web.rest.overview
The WebApi REST/HAL implementation is built on top of ASP.NET Core and easily allows defining resources and their associated relations (named links). This allows an API to be easily discovered by clients since standards based.
- Provides a simple and non-intrusive implementation of the HAL Specification.
- Type-safe way of specifying resource relations (named links) URIs without having hard-coded URL strings.
- Resource links are specified external to the resources and API controllers.
- Provides a fluent API based on controller and model types for URL specification.
- Delegates all URL generation to ASP.NET Core infrastructure.
- Easy way of specifying embedded resources.
The implementation is contained within the following NuGet packages:
- NetFusion.Rest.Resources - Contains classes representing resources used to add links and embedded resources to response models.
- NetFusion.Rest.Server - provides the code used by ASP.NET WebApi services for specifying the generation of resource URLs.
- NetFusion.Rest.Client - Standalone package containing HTTP client for invoking REST/HAL based services.
- NetFusion.Rest.Common - Contains common types shared across all other assemblies.
The concepts behind the HAL specification are rather simple. Normally, APIs return models defining the contract of an API methods that the client programs against. This is all fine and dandy if you are consuming your own APIs. However, when one developer consumes another developer's API, the following usually takes place:
- The developer consuming the API spends half their day jumping back to the server-side code to study the controller's methods to determine the URL to be called.
- Documentation is provided describing each of the API methods (Since all developers love writing documentation).
- The consuming developer gets pissed at the API developer for changing the API and not telling them.
The above is solved by having the service APIs describe how the client should interact with the API. The HAL specification allows this by associating Links (also known as relations) to returned models. These links are also sometimes called Controls and are identified by a key name. The client does not hard-code URLs to the service API but rather determines them by looking at the returned resource. These links allow the client to complete the following:
- Take actions on the returned resource.
- Load other resources related to current resource.
Also, links can be used to convey to the client if the user has permissions for the associated action. If a given link is not specified, then the client can use this to disable the action within the user-interface.
A parent resource can have one or more embedded resources or resource collections. By using embedded resources instead of having to define the relations within the returned models, allows the API to be easily extended by embedding additional resources. Also, embedded resources can also be excluded if the user of the calling client does not have permissions to the resource.
Below is a representation of the design.
