NAME

Catmandu::Importer::getJSON - Load JSON-encoded data from a server using a GET HTTP request

VERSION

version 0.1.1

SYNOPSIS

The following three examples are equivalent:

    Catmandu::Importer::getJSON->new(
        file => \"http://example.org/alice.json\nhttp://example.org/bob.json"
    )->each(sub { my ($record) = @_; ... );

    Catmandu::Importer::getJSON->new(
        url  => "http://example.org",
        file => \"/alice.json\n/bob.json"
    )->each(sub { my ($record) = @_; ... );
    
    Catmandu::Importer::getJSON->new(
        url  => "http://example.org/{name}.json",
        file => \"{\"name\":\"alice\"}\n{\"name\":\"bob\"}"
    )->each(sub { my ($record) = @_; ... );

For more convenience the catmandu command line client can be used:

    echo http://example.org/alice.json | catmandu convert getJSON to YAML
    catmandu convert getJSON --from http://example.org/alice.json to YAML

DESCRIPTION

This Catmandu::Importer performs a HTTP GET request to load JSON-encoded data from a server. The importer expects a line-separated input. Each line corresponds to a HTTP request that is mapped to a JSON-record on success. The following input formats are accepted:

plain URL

A line that starts with "http://" or "https://" is used as plain URL.

URL path

A line that starts with "/" is appended to the configured url parameter.

variables

A JSON object with variables to be used with an URL template or as HTTP query parameters. For instance the input line {"name":"Karl Marx"} with URL http://api.lobid.org/person or the input line {"entity":"person","name":"Karl Marx"} with URL template http://api.lobid.org/{entity}{?id}{?name}{?q} are both expanded to http://api.lobid.org/person?name=Karl+Marx.

If the JSON data returned in a HTTP response is a JSON array, its elements are imported as multiple items. If a JSON object is returned, it is imported as one item.

CONFIGURATION

url

An URI or an URI templates (URI::Template) as defined by RFC 6570 to load JSON from. If no url is configured, plain URLs must be provided as input or option from must be used instead.

from

A plain URL to load JSON without reading any input lines.

timeout / agent / proxy / headers

Optional HTTP client settings.

client

Instance of a Furl HTTP client to perform requests with.

file / fh

Input to read lines from (see Catmandu::Importer). Defaults to STDIN.

fix

An optional fix to be applied on every item (see Catmandu::Fix).

LIMITATIONS

Error handling is very limited.

Future versions of this module may also support asynchronous HTTP fetching modules such as HTTP::Async, for retrieving multiple URLs at the same time..

SEE ALSO

Catmandu

AUTHOR

Jakob Voß

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Jakob Voß.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.