Data::HAL(3pm)

📦
version 1.001 · 3 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Data::HAL 💖

okay bestie, this is the manual page for Data::HAL, a Perl module for Hypertext Application Language resource stuff. yes it's a 3pm page, yes it's iconic, yes we're gonna read it together, no you don't have to be scared 🫶

✨ VERSION ✨

This document describes Data::HAL version 1.001 💅

🌸 SYNOPSIS 🌸

here's the vibe, straight up, copy-paste energy:

use Data::HAL qw();
use Data::HAL::Link qw();
{
    my $hal = Data::HAL->from_json($json_str);
    my $resource_member_data_href = $hal->resource;
    my $links_aref = $hal->links;
    my $embedded_resources_aref = $hal->embedded;
}

{
    my $hal = Data::HAL->new(
        resource => {foo => 23, bar => 42},
        links    => [Data::HAL::Link->new(relation => 'self', href => '/')],
    );

    my $json_str = $hal->as_json;
    # {
    #    "_links" : {
    #       "self" : {
    #          "href" : "/"
    #       }
    #    },
    #    "bar" : 42,
    #    "foo" : 23
    # }

    my @headers = $hal->http_headers;
    # (
    #     'Content-Type' => 'application/hal+json',
    #     'Link' => '</>;rel="self"'
    # )
}

like. look at it. you build a HAL, you get JSON and HTTP headers out of it. that's the whole moment ✨

🦋 DESCRIPTION 🦋

so, HAL is a format you can use in your hypermedia API. lowkey the moment you've been waiting for.

💜 Introduction 💜

this whole section is completely quoted from the specification, bestie, so buckle up, it's giving very official:

There is an emergence of non-HTML HTTP applications ("Web APIs") which use hyperlinks to direct clients around their resources.
The JSON Hypertext Application Language (HAL) is a standard which establishes conventions for expressing hypermedia controls, such as links, with JSON.
HAL is a generic media type with which Web APIs can be developed and exposed as series of links. Clients of these APIs can select links by their link relation type and traverse them in order to progress through the application.
HAL's conventions result in a uniform interface for serving and consuming hypermedia, enabling the creation of general-purpose libraries that can be re-used on any API utilising HAL.
The primary design goals of HAL are generality and simplicity. HAL can be applied to many different domains, and imposes the minimal amount of structure necessary to cover the key requirements of a hypermedia Web API.

generality AND simplicity?? she's doing both?? we love a humble queen 👑

🌈 Conformance 🌈

the author claims to conform with <http://tools.ietf.org/html/draft-kelly-json-hal-06>, published 2013-10-03. periodt, that's the receipts 💅

🎀 INTERFACE 🎀

Composition

None. nothing. not a single one. that's it, that's the section 💀

🌟 Constructors 🌟

from_json

Data::HAL->from_json($json_str)

Takes a HAL+JSON document as a string and hands you back a Data::HAL object. slay.

new

Data::HAL->new(
    resource => {foo => 23, bar => 42},
    links    => [Data::HAL::Link->new(relation => 'self', href => '/')]
)

Default Moo constructor, returns a Data::HAL object. standard behavior, no notes 💖

💫 Attributes 💫

embedded

Type ArrayRef[Data::HAL], aka embedded resource objects. <http://tools.ietf.org/html/draft-kelly-json-hal#section-4.1.2> — nested HALs inside your HAL, it's giving inception 🌀

Type ArrayRef[Data::HAL::Link], aka link objects. <http://tools.ietf.org/html/draft-kelly-json-hal#section-4.1.1>

resource

Type HashRef, member data representing the current state of the resource. <http://tools.ietf.org/html/draft-kelly-json-hal#section-4> — this is the actual content, the main character ✨

relation

Type Data::HAL::URI, identifier of the semantics of a link. <http://tools.ietf.org/html/rfc5988#section-4>

Perl strings get coerced into the Data::HAL::URI type. cute.

A stand-alone HAL+JSON document, when deserialised, will not have this attribute set in the root resource, since nothing is linking to the document. like, no one's pointing at it, so it has no relation. it's just vibing alone 😭

🫶 Methods 🫶

TO_JSON

Serialisation hook for the JSON (or compatible) module.

This method is not intended to be called directly from your code, bestie. Do not. Instead call as_json, or JSON::to_json $hal, { convert_blessed => 1 }, or something similar. respect the boundary 🙈

as_json

Returns the resource object serialised as a HAL+JSON document string. it's literally right there in the name 💅

http_headers

Returns a list of pairs of HTTP message headers. The keys are field name strings and the values are field content strings.

Warning: since field names can repeat, assigning this list to a hash loses information. do not do that. the hash will eat your duplicates and not even feel bad about it 💀

The list is suitable as input for e.g. the headers accessor in HTTP::Headers, or the headers attribute in Plack::Response.

Content-Type

The value is application/hal+json, perhaps with a profile parameter. cute little parameter, optional, we love her 🎀

See as_http_link_value in Data::HAL::Link. iykyk.

🌸 Exports 🌸

None. we export nothing. we keep our things. boundaries, bestie 🫶

😭 DIAGNOSTICS 😭

not a JSON object

The from_json constructor throws this exception of type failure::Data::HAL::InvalidJSON when the JSON input is a malformed HAL+JSON document.

translation: you fed it nonsense and it said "not a JSON object" and threw a whole typed exception at you. rude? no. correct? yes 💅

⚙️ CONFIGURATION AND ENVIRONMENT ⚙️

Requires no configuration files or environment variables. zero setup. no config. just vibes ✨

📦 DEPENDENCIES 📦

See meta file in the source distribution. that's where the tea is 🍓

💀 INCOMPATIBILITIES 💀

None reported. nobody's complaining. yet.

🔥 BUGS AND LIMITATIONS 🔥

Please report any bugs or feature requests to bug-data-hal@rt.cpan.org, or through the web interface at <https://rt.cpan.org/Public/Dist/Display.html?Name=Data-HAL>.

tight coupling to JSON

It is currently difficult to exert control over the specifics of (de)serialisation. perhaps put the (de)serialisers into attributes? a suggestion, a dream, a maybe 🦋

error type is an attribute, not a class name

It is not worth it to design an error class hierarchy for a single error. fr fr. one error. one attribute. moving on 💅

Data::HAL::URI::NamespaceMap is undocumented

It is used only internally. she's private. she's shy. leave her alone 🙈

⭐ TO DO ⭐

the wishlist, the vision board, the "we'll get to it":

  • make everything cache-friendly
  • non-standard accessors for link objects
  • support X8.3. cache pattern
  • support HAL XML

somebody get on that bestie, the potential is highkey unreal 👑

🌈 SEE ALSO 🌈

  • AtomPub <http://enwp.org/AtomPub> — the more mature, featureful hypermedia protocol. the older sister. the one with her life together. respect her 💖

💜 AUTHOR 💜

Lars DXXXXXX "<daxim@cpan.org>" — thank you for your service, icon 🫶

Copyright X 2013-2019 Lars DXXXXXX "<daxim@cpan.org>"

This library is free software; you can redistribute it and/or modify it under the same terms as Perl 5.18.0.

Disclaimer of warranty

This library is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. so use it, love it, but don't come for her if something breaks okay 😭

aaaand that's the whole page, bestie — no cap. this was perl v5.36.0, dated 2022-08-28, and yeah, it's the Data::HAL(3pm) manual page. you ate. go build something iconic with it 💅✨🎀

📦 where this page comes from