Hypertext Application Language (HAL)

Hypertext Application Language (HAL)

HAL, called Hypertext Application Language, is a simple data format that introduces hyperlink features in an API in a simple, unified form, making the API more discoverable (discoverable) stronger, and has the characteristics of self-description. Using the HAL API is easier to call from a third-party open Source Library and is easy to use, allowing developers to process API data just like normal JSON data. For more information about HAL, refer to the official website: http://stateless.co/hal_specification.html.

Example

The following is a typical response data for an API that uses the HAL.

12345678910111213141516171819202122232425262728293031323334

{    "_links": {        "self": { "href": "/orders" },        "curies": [{ "name": "ea", "href": "http://example.com/docs/rels/{rel}", "templated": true }],        "next": { "href": "/orders?page=2" },        "ea:find": {            "href": "/orders{?id}",            "templated": true        }    },    "currentlyProcessing": 14,    "shippedToday": 20,    "_embedded": {        "ea:order": [{            "_links": {                "self": { "href": "/orders/123" },                "ea:basket": { "href": "/baskets/98712" },                "ea:customer": { "href": "/customers/7809" }            },            "total": 30.00,            "currency": "USD",            "status": "shipped"        }, {            "_links": {                "self": { "href": "/orders/124" },                "ea:basket": { "href": "/baskets/97213" },                "ea:customer": { "href": "/customers/12369" }            },            "total": 20.00,            "currency": "USD",            "status": "processing"        }]    }}

In the JSON data above, the highlighted lines are actually part of the data, and the rest is added hyperlinks to locate other resources related to the current resource (object). For example, under the _embedded node contains two order information, under the _links node of the order information, it contains access links to other resources related to the order, for example, by accessing the/customers/7809 link, you can get the customer information of the first order. In addition, in the HAL, a hyperlink can be a template, a template link can be given a name, and a templated is specified as true. For example, above, the curies link in the child, specifies the link template for the API document, then, by accessing Http://example.com/docs/rels/find, you can obtain a document about obtaining a sales order Details API by accessing the http:/ /example.com/docs/rels/order, you can get documentation on the sales order API. In addition, the example above also contains a link to get the next page of data (next link), so the client only needs to call the API once to get access links to other APIs associated with it.

. NET Core Implementations

In Java, spring data is used by default in the new data Service API, with HAL, which returns the format Application/hal+json or Application/hal+xml (Hal can have JSON and XML in two formats , this article only discusses JSON format). So, I implemented the HAL programming model based on. NET core, which makes it easy to enable HAL functionality in the. NET core Web API in the future. The open source address for the project is: Https://github.com/daxnet/hal. I also continued to integrate through Jenkins, releasing nuget packages that support the. NET Framework 4.6.1 and NET Standard 1.6, so that you can use the HAL Library in. NET core in both the classic. NET Framework.

In Visual Studio, add NuGet Feed:https://www.myget.org/f/daxnet-utils/api/v3/index.json to NuGet Package Manager

Then, on the console Application (console application) project, select Manage NuGet Packages, open nuget,package Source, select the one that you just added, and then select HAL and click Install.

When the installation is complete, enter the following code:

123456789101112131415161718192021222324252627282930313233

usingSystem;using Hal.Builders;namespaceConsoleApp8{    publicclassProgram    {        publicstaticvoid Main(string[] args)        {            varbuilder = newResourceBuilder();            varresource = builder                .WithState(new{ currentlyProcessing = 14, shippedToday = 20 })                .AddSelfLink().WithLinkItem("/orders")                .AddCuriesLink().WithLinkItem("http://example.com/docs/rels/{rel}", "ea", true)                .AddLink("next").WithLinkItem("/orders?page=2")                .AddLink("ea:find").WithLinkItem("/orders{?id}", templated: true)                .AddEmbedded("ea:order")                    .Resource(newResourceBuilder()                        .WithState(new{ total = 30.00F, currency = "USD", status = "shipped"})                        .AddSelfLink().WithLinkItem("/orders/123")                        .AddLink("ea:basket").WithLinkItem("/baskets/98712")                        .AddLink("ea:customer").WithLinkItem("/customers/7809"))                    .Resource(newResourceBuilder()                        .WithState(new{ total = 20.00F, currency = "USD", status = "processing" })                        .AddSelfLink().WithLinkItem("/orders/124")                        .AddLink("ea:basket").WithLinkItem("/baskets/97213")                        .AddLink("ea:customer").WithLinkItem("/customers/12369"))                .Build();            Console.WriteLine(resource);        }    }}

Run for a try? Have you already output the HAL JSON data from the previous example (below)?

One of the highlights of this development library is the use of the Fluent interface (fluent API) programming style, which makes it very easy for developers to use this library to produce the required HAL data. The implementation of the fluent interface combines the adorner (Decorator) mode and the C # extension method, all defined under the Hal.builders namespace, where interested readers can download the source code view.

Enclose the object model class diagram for the entire HAL:

Summarize

I believe this library should be the first open Source Library under. NET core that implements the HAL specification completely, which is published under the MIT license and is commercially friendly, welcome to use and make valuable comments. After the bug is discovered, it is also welcome to submit it in issue or pull request.

Category:. NET Core

Hypertext Application Language (HAL)