view release on metacpan or  search on metacpan

lib/LWP/JSON/Tiny.pm  view on Meta::CPAN

package LWP::JSON::Tiny;

use strict;
use warnings;
no warnings 'uninitialized';

use HTTP::Request::JSON;
use HTTP::Response::JSON;
use JSON::MaybeXS;
use LWP;
use LWP::UserAgent::JSON;

# Have you updated the version number in the POD below?
our $VERSION = '0.014';
$VERSION = eval $VERSION;

=head1 NAME

LWP::JSON::Tiny - use JSON natively with LWP objects

=head1 VERSION

This is version 0.014.

=head1 SYNOPSIS

 my $user_agent = LWP::UserAgent::JSON->new;
 my $request = HTTP::Request::JSON->new(POST => "$url_prefix/upload_dance");
 $request->json_content({ contents => [qw(badger mushroom snake)] });
 my $response = $user_agent->request($request);
 if (my $upload_id = $response->json_content->{upload}{id}) {
     print "Uploaded Weebl rip-off: $upload_id\n";
 }

 my $other_response = $some_other_object->do_stuff(...);
 if (LWP::UserAgent::JSON->rebless_maybe($other_response)) {
     do_something($other_response->json_content);
 }

=head1 DESCRIPTION

A lot of RESTful API integration involves pointless busy work with setting
accept and content-type headers, remembering how Unicode is supposed to work
and so on. This is a very simple wrapper around HTTP::Request and
HTTP::Response that handles all of that for you.

There are four classes in this distribution:

=over

=item LWP::JSON::Tiny

Pulls in the other classes, and implements a L</"json_object"> method which
returns a JSON object, suitable for parsing and emitting JSON.

=item HTTP::Request::JSON

A subclass of HTTP::Request. It automatically sets the Accept header to
C<application/json>, and implements a
L<json_content|HTTP::Request::JSON/json_content> method
which takes a JSONable data structure and sets the content-type.

=item HTTP::Response::JSON

A subclass of HTTP::Response. It implements a
L<json_content|HTTP::Response::JSON/json_content> method which
decodes the JSON contents into a Perl data structure.

=item LWP::UserAgent::JSON

A subclass of LWP::UserAgent. It does only one thing: is a response has
content-type JSON, it reblesses it into a HTTP::Response::JSON object.
It exposes this method L<rebless_maybe|LWP::UserAgent::JSON/rebless_maybe>
for convenience, if you ever get an HTTP::Response object back from some
other class.

=back

As befits a ::Tiny distribution, sensible defaults are applied. If you really
need to tweak this stuff (e.g. you really care about the very slight
performance impact of sorting all hash keys), look at the individual
modules' documentation for how you can subclass behaviour.

=head2 Class methods

=head3 json_object

 Out: $json

Returns a JSON object, as per JSON::MaybeXS->new. Cached across multiple
calls for speed.

Note that the JSON object has the utf8 option disabled. I<This is deliberate>.
The documentation for JSON::XS is very clear that the utf8 option means both
that it should spit out JSON in UTF8, and that it should expect strings
passed to it to be in UTF8 encoding. This latter part is daft, and violates
the best practice that character encoding should be dealt with at the
outermost layer.

=cut

{