view release on metacpan or  search on metacpan

lib/Data/HAL.pm  view on Meta::CPAN

L<< identifier of the semantics of a link|http://tools.ietf.org/html/rfc5988#section-4 >>

Perl strings are coerced to the L<Data::HAL::URI> type.

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.

=head2 Methods

=head3 C<TO_JSON>

Serialisation hook for the L<JSON> (or compatible) module.

This method is not intended to be called directly from your code. Instead call L</as_json> or
C<< JSON::to_json $hal, { convert_blessed => 1 } >> or similar.

=head3 C<as_json>

Returns the resource object serialised as a HAL+JSON document string.

=head3 C<http_headers>

Returns a list of pairs of HTTP message headers. The keys are field name strings and the values are field content
strings. B<Warning>: since field names can repeat, assigning this list to a hash loses information.

The list is suitable as input for e.g. the
L<< C<headers> accessor in HTTP::Headers|HTTP::Headers/$h->header( $f1 => $v1, $f2 => $v2, ... ) >>
or the L<< C<headers> attribute in Plack::Response|Plack::Response/headers >>.

=head4 C<Content-Type>

The value is C<application/hal+json>, perhaps with a C<profile> parameter.

=head4 C<Link>

See L<Data::HAL::Link/as_http_link_value>.

=head2 Exports

None.

=head1 DIAGNOSTICS

=head2 C<not a JSON object>

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

=head1 CONFIGURATION AND ENVIRONMENT

Requires no configuration files or environment variables.

=head1 DEPENDENCIES

See meta file in the source distribution.

=head1 INCOMPATIBILITIES

None reported.

=head1 BUGS AND LIMITATIONS

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

=head2 tight coupling to JSON

It is currently difficult to exert control over the specifics of (de)serialisation, perhaps put the (de)serialisers
into attributes?

=head2 error type is an attribute, not a class name

It is not worth it to design an error class hierarchy for a single error.

=head2 Data::HAL::URI::NamespaceMap is undocumented

It is used only internally.

=head1 TO DO

=over

=item make everything cache-friendly

=item non-standard accessors for link objects

=item support §8.3. cache pattern

=item support HAL XML

=back

=head1 SEE ALSO

L<AtomPub|http://enwp.org/AtomPub>, the more mature, featureful hypermedia protocol

=head1 AUTHOR

Lars Dɪᴇᴄᴋᴏᴡ C<< <daxim@cpan.org> >>

=head1 LICENCE AND COPYRIGHT

Copyright © 2013-2019 Lars Dɪᴇᴄᴋᴏᴡ C<< <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.

=head2 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.