Web-API-2.6/000755 000765 000024 00000000000 13567130466 012451 5ustar00levstaff000000 000000 Web-API-2.6/Changes000644 000765 000024 00000016577 13567130466 013764 0ustar00levstaff000000 000000 ================================================== Changes from 2018-11-26 00:00:00 +0000 to present. ================================================== ---------------------------------------- version 2.6 at 2019-11-26 04:59:31 +0000 ---------------------------------------- Change: 7da3392c4a45d33734f9e88ecf36ccb6432ed271 Author: Tobias Kirschstein Date : 2019-11-26 17:59:19 +0000 auth header format as an attribute Change: 5c8c9874b4ce8fb98a04d4b678c7397c61dd34bd Author: Tobias Kirschstein Date : 2019-11-18 15:46:57 +0000 cleanup after dzil ---------------------------------------- version 2.5 at 2019-11-18 02:35:12 +0000 ---------------------------------------- Change: 73517c3caf077a4de1a9d2ac90e168c828aedc87 Author: Tobias Kirschstein Date : 2019-11-18 15:35:12 +0000 simple test system support Change: c8c0c4519966072b8c8e2b054655475937965b16 Author: Tobias Kirschstein Date : 2019-01-15 17:01:21 +0000 v2.4.1 Change: f7531fae482f31b3e64fe60e3c10a1dd2ddfcdeb Author: Tobias Kirschstein Date : 2019-01-15 17:00:51 +0000 updated pod from merges Change: 34174e3c23bebb8d5df30c38db88097ee9b24504 Author: Tobias Kirschstein Date : 2019-01-15 16:58:31 +0000 Merge branch 'master' of github.com:nupfel/Web-API Change: 039f7473ca7ea46c1045e5c60f7f8622ba7450cb Author: Tobias Kirschstein Date : 2019-01-15 16:55:50 +0000 ignore cpanfile Change: 8a0810d23f89ce59301bc475ae3b8599bfd4f4f2 Author: Tobias Kirschstein Date : 2019-01-09 15:37:12 +0000 Merge pull request #28 from pkg-perl-tools/pkg-perl-1517091610 Grammar correction Change: 47afb9f1458baa1e3f67c80a17e6573626bb1612 Author: Tobias Kirschstein Date : 2019-01-09 15:36:30 +0000 Merge pull request #29 from manwar/tidy-up-abstract Tidied up ABSTRACT in pod. Change: abcb468333ce206ec81d05daad2f54c821649641 Author: Tobias Kirschstein Date : 2019-01-08 01:33:00 +0000 generate and distribute cpanfile Change: bf15211921c1ac419de1870f9c091a136d990af9 Author: Tobias Kirschstein Date : 2019-01-08 01:25:28 +0000 upload release to github Change: a1d7942c1715ecde48bdced3800ef69ac71ad57c Author: Tobias Kirschstein Date : 2019-01-08 01:25:13 +0000 separate out query_keys from options Change: 0bacbdf8888f2b1f2aa67e1fbdabc8da0ec75d72 Author: Mohammad S Anwar Date : 2018-12-25 11:18:22 +0000 Tidied up ABSTRACT in pod. Change: 98be5b3606ddc7d7b1741cc2be18fc6fb357ee12 Author: Tobias Kirschstein Date : 2018-12-25 23:56:47 +0000 minor version bump Change: b640a74053ba751c941bd97e1523deca73c24053 Author: Tobias Kirschstein Date : 2018-12-25 23:56:28 +0000 ignore decoding whitespace or empty responses Change: b58cfa36e991f5af15d50638f59f72f77c20802b Author: Christopher Hoskin Date : 2018-01-27 22:21:27 +0000 Grammar correction ---------------------------------------- version 2.3 at 2018-12-25 10:23:48 +0000 ---------------------------------------- Change: 5745eb37374e0faf4b732ea7625914d4e8c9ee9d Author: Tobias Kirschstein Date : 2018-12-25 23:23:48 +0000 Merge branch 'master' of github.com:nupfel/Web-API Change: 6975533993cbdf4030ae42ccb3eb19e13dc0ab69 Author: Tobias Kirschstein Date : 2018-12-25 23:23:14 +0000 api_version and auth method 'header' via Token, bump to 2.3 Change: 6107849c9e68490be2b9b39826eea365692269ea Author: Tobias Kirschstein Date : 2018-07-31 21:52:09 +0000 ignore .build Change: a63841d5d55eb3d4d1c2e918ef6c74428c4aaff6 Author: Tobias Kirschstein Date : 2017-10-21 18:34:38 +0000 v2.2.3 Change: 17fb57d4f3f7484b7b20744db938204fdc435b40 Author: Tobias Kirschstein Date : 2017-10-21 18:34:04 +0000 require at least 6.04 of HTTP::Cookies which provides get_cookies() Change: 6343894258b675ba8e9689436e21ff6144bec169 Author: Tobias Kirschstein Date : 2017-06-13 03:34:42 +0000 v2.2.2 Change: 4720a529a86e432a2db6ca63e639c8084e372441 Author: Tobias Kirschstein Date : 2017-06-13 03:30:23 +0000 return cookies hash in response structure as well Change: a899f0de5a9350b31c587983167dd22af0ff8921 Author: Tobias Kirschstein Date : 2017-05-10 00:30:38 +0000 v2.2.1 Change: 89d064dc29556fcd5c0cd4ca18d34e89ba0109ce Author: Tobias Kirschstein Date : 2017-05-10 00:29:58 +0000 catch DESTROY calls. fixes #26 Change: 6a5c2e574d90c7611dbdca9df6bc523ccc04280d Author: Tobias Kirschstein Date : 2017-05-10 00:29:03 +0000 restore documentation fixes Change: ee7294170a5ddda0f22091d6facdedd838974731 Author: Tobias Kirschstein Date : 2016-09-10 00:29:57 +0000 Merge branch 'master' of github.com:nupfel/Web-API Change: 7c2634ab2c98a53f17d6c00a4d5265d7de89c28d Author: Jeremy Mates Date : 2016-09-10 00:29:34 +0000 Spelling fixes, some L, other documentation tweaks. Change: 79e34cdb04115f134dd625c9a129d83ba976f055 Author: sam Date : 2016-09-10 00:29:33 +0000 remove that stuff Change: ae357fcf2241f77768b9bfea43757ec0546c0c7c Author: sam Date : 2016-09-10 00:29:33 +0000 adding Build.PL and META files for installation Change: 7872546af96babbd50e509eecaf9c5fc48d5fdf0 Author: Tobias Kirschstein Date : 2016-09-10 00:24:55 +0000 fixed example usage constructor Change: 31fc25c58ce4d065450ef7c5441195a8c5772e02 Author: Tobias Kirschstein Date : 2016-09-10 00:24:05 +0000 use Data::Printer to avoid mangling integers. fixes #24 Change: 2aecd21d1b0bb3b08084d2961f60be9a23a2ff02 Author: Tobias Kirschstein Date : 2016-04-03 15:29:51 +0000 Merge pull request #20 from thrig/master Spelling fixes, some L, other documentation tweaks. Change: daa06fdc559d31e11cb959ac3f38f5bd5ece9e22 Author: Jeremy Mates Date : 2016-01-09 16:00:18 +0000 Spelling fixes, some L, other documentation tweaks. Change: b68331c08d658a7aa5985d8fc56ade7e2027be18 Author: Tobias Kirschstein Date : 2015-11-06 09:26:39 +0000 Merge pull request #19 from sthompsonxyz/master adding Build.PL and META files for installation Change: 9009e6f47334c75a847f5bcac1f43c6df0c8b778 Author: sam Date : 2015-11-05 16:43:38 +0000 remove that stuff Change: 47aeb7c185fdf6f6894a9366bc54708d344a431e Author: sam Date : 2015-11-05 13:44:55 +0000 adding Build.PL and META files for installation Change: d4425a8b008fc4846eb345f637aeedc37a8ca487 Author: Tobias Kirschstein Date : 2014-12-20 12:21:39 +0000 use caller with parenthesis to silence warning. fixes #18 ================================================= Plus 22 releases after 2018-11-26 00:00:00 +0000. ================================================= Web-API-2.6/CONTRIBUTORS.txt000644 000765 000024 00000000341 13567130466 015145 0ustar00levstaff000000 000000 # Contributions to the Web-API module ## Creator & Maintainer * Tobias Kirschstein ## Contributors In chronological order: * Robert Norris * Support mandatory deep hash params Web-API-2.6/cpanfile000644 000765 000024 00000001422 13567130466 014154 0ustar00levstaff000000 000000 requires "Carp" => "0"; requires "Data::Printer" => "0"; requires "Data::Random" => "0"; requires "HTTP::Cookies" => "6.04"; requires "JSON" => "0"; requires "LWP::UserAgent" => "0"; requires "Mouse::Role" => "0"; requires "Net::OAuth" => "0"; requires "Time::HiRes" => "0"; requires "URI" => "0"; requires "URI::Escape::XS" => "0"; requires "URI::QueryParam" => "0"; requires "XML::Simple" => "0"; requires "experimental" => "0"; requires "perl" => "5.010001"; on 'configure' => sub { requires "ExtUtils::MakeMaker" => "0"; }; on 'develop' => sub { requires "Pod::Coverage::TrustPod" => "0"; requires "Test::EOL" => "0"; requires "Test::More" => "0.88"; requires "Test::Perl::Critic" => "0"; requires "Test::Pod" => "1.41"; requires "Test::Pod::Coverage" => "1.08"; }; Web-API-2.6/dist.ini000644 000765 000024 00000002330 13567130466 014113 0ustar00levstaff000000 000000 name = Web-API author = Tobias Kirschstein license = BSD copyright_holder = Tobias Kirschstein copyright_year = 2013 [Git::NextVersion] first_version = 0.1 [ChangelogFromGit] file_name = Changes exclude_message = ^(forgot|typo) [Git::GatherDir] include_untracked = 1 exclude_filename = .shipit exclude_filename = .lwpcookies exclude_match = \.(sw(p|o)|vimbk)$ ; copy cpanfile back to repo dis [CopyFilesFromBuild] copy = cpanfile [Git::Check] allow_dirty = dist.ini allow_dirty = README.pod allow_dirty = cpanfile changelog = Changes ; this is the default untracked_files = warn ; default value (can also be "warn" or "ignore") [OurPkgVersion] [MetaJSON] ; generate META.json (v2) [CPANFile] ; generate cpanfile [PodWeaver] [PodSyntaxTests] [PodCoverageTests] [Test::Perl::Critic] [AutoPrereqs] [@GitHub] wiki = 1 bugs = 1 metacpan = 1 [ReadmeAnyFromPod / ReadmePodInRoot] type = pod filename = README.pod location = root [@Filter] -bundle = @Basic -remove = GatherDir ;-remove = UploadToCPAN ; uncomment to prevent CPAN upload [Git::Tag] signed = 1 [Git::Commit] allow_dirty = README.pod [Git::Push] [GitHub::UploadRelease] [TestRelease] [Test::EOL] [Clean] Web-API-2.6/lib/000755 000765 000024 00000000000 13567130466 013217 5ustar00levstaff000000 000000 Web-API-2.6/LICENSE000644 000765 000024 00000003102 13567130466 013452 0ustar00levstaff000000 000000 This software is Copyright (c) 2013 by Tobias Kirschstein. This is free software, licensed under: The (three-clause) BSD License The BSD License Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of Tobias Kirschstein nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Web-API-2.6/Makefile.PL000644 000765 000024 00000003124 13567130466 014423 0ustar00levstaff000000 000000 # This file was automatically generated by Dist::Zilla::Plugin::MakeMaker v6.012. use strict; use warnings; use 5.010001; use ExtUtils::MakeMaker; my %WriteMakefileArgs = ( "ABSTRACT" => "A Simple base module to implement almost every RESTful API with just a few lines of configuration", "AUTHOR" => "Tobias Kirschstein ", "CONFIGURE_REQUIRES" => { "ExtUtils::MakeMaker" => 0 }, "DISTNAME" => "Web-API", "LICENSE" => "bsd", "MIN_PERL_VERSION" => "5.010001", "NAME" => "Web::API", "PREREQ_PM" => { "Carp" => 0, "Data::Printer" => 0, "Data::Random" => 0, "HTTP::Cookies" => "6.04", "JSON" => 0, "LWP::UserAgent" => 0, "Mouse::Role" => 0, "Net::OAuth" => 0, "Time::HiRes" => 0, "URI" => 0, "URI::Escape::XS" => 0, "URI::QueryParam" => 0, "XML::Simple" => 0, "experimental" => 0 }, "VERSION" => "2.6", "test" => { "TESTS" => "t/*.t" } ); my %FallbackPrereqs = ( "Carp" => 0, "Data::Printer" => 0, "Data::Random" => 0, "HTTP::Cookies" => "6.04", "JSON" => 0, "LWP::UserAgent" => 0, "Mouse::Role" => 0, "Net::OAuth" => 0, "Time::HiRes" => 0, "URI" => 0, "URI::Escape::XS" => 0, "URI::QueryParam" => 0, "XML::Simple" => 0, "experimental" => 0 ); unless ( eval { ExtUtils::MakeMaker->VERSION(6.63_03) } ) { delete $WriteMakefileArgs{TEST_REQUIRES}; delete $WriteMakefileArgs{BUILD_REQUIRES}; $WriteMakefileArgs{PREREQ_PM} = \%FallbackPrereqs; } delete $WriteMakefileArgs{CONFIGURE_REQUIRES} unless eval { ExtUtils::MakeMaker->VERSION(6.52) }; WriteMakefile(%WriteMakefileArgs); Web-API-2.6/MANIFEST000644 000765 000024 00000000421 13567130466 013577 0ustar00levstaff000000 000000 # This file was automatically generated by Dist::Zilla::Plugin::Manifest v6.012. CONTRIBUTORS.txt Changes LICENSE MANIFEST META.json META.yml Makefile.PL README cpanfile dist.ini lib/Web/API.pm t/author-critic.t t/author-eol.t t/author-pod-coverage.t t/author-pod-syntax.t Web-API-2.6/META.json000644 000765 000024 00000003627 13567130466 014102 0ustar00levstaff000000 000000 { "abstract" : "A Simple base module to implement almost every RESTful API with just a few lines of configuration", "author" : [ "Tobias Kirschstein " ], "dynamic_config" : 0, "generated_by" : "Dist::Zilla version 6.012, CPAN::Meta::Converter version 2.150010", "license" : [ "bsd" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : 2 }, "name" : "Web-API", "prereqs" : { "configure" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "develop" : { "requires" : { "Pod::Coverage::TrustPod" : "0", "Test::EOL" : "0", "Test::More" : "0.88", "Test::Perl::Critic" : "0", "Test::Pod" : "1.41", "Test::Pod::Coverage" : "1.08" } }, "runtime" : { "requires" : { "Carp" : "0", "Data::Printer" : "0", "Data::Random" : "0", "HTTP::Cookies" : "6.04", "JSON" : "0", "LWP::UserAgent" : "0", "Mouse::Role" : "0", "Net::OAuth" : "0", "Time::HiRes" : "0", "URI" : "0", "URI::Escape::XS" : "0", "URI::QueryParam" : "0", "XML::Simple" : "0", "experimental" : "0", "perl" : "5.010001" } } }, "release_status" : "stable", "resources" : { "bugtracker" : { "web" : "https://github.com/nupfel/Web-API/issues" }, "homepage" : "https://github.com/nupfel/Web-API/wiki", "repository" : { "type" : "git", "url" : "git://github.com/nupfel/Web-API.git", "web" : "https://github.com/nupfel/Web-API" } }, "version" : "2.6", "x_generated_by_perl" : "v5.27.0", "x_serialization_backend" : "Cpanel::JSON::XS version 3.0233" } Web-API-2.6/META.yml000644 000765 000024 00000001750 13567130466 013725 0ustar00levstaff000000 000000 --- abstract: 'A Simple base module to implement almost every RESTful API with just a few lines of configuration' author: - 'Tobias Kirschstein ' build_requires: {} configure_requires: ExtUtils::MakeMaker: '0' dynamic_config: 0 generated_by: 'Dist::Zilla version 6.012, CPAN::Meta::Converter version 2.150010' license: bsd meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: '1.4' name: Web-API requires: Carp: '0' Data::Printer: '0' Data::Random: '0' HTTP::Cookies: '6.04' JSON: '0' LWP::UserAgent: '0' Mouse::Role: '0' Net::OAuth: '0' Time::HiRes: '0' URI: '0' URI::Escape::XS: '0' URI::QueryParam: '0' XML::Simple: '0' experimental: '0' perl: '5.010001' resources: bugtracker: https://github.com/nupfel/Web-API/issues homepage: https://github.com/nupfel/Web-API/wiki repository: git://github.com/nupfel/Web-API.git version: '2.6' x_generated_by_perl: v5.27.0 x_serialization_backend: 'YAML::Tiny version 1.70' Web-API-2.6/README000644 000765 000024 00000000560 13567130466 013332 0ustar00levstaff000000 000000 This archive contains the distribution Web-API, version 2.6: A Simple base module to implement almost every RESTful API with just a few lines of configuration This software is Copyright (c) 2013 by Tobias Kirschstein. This is free software, licensed under: The (three-clause) BSD License This README file was generated by Dist::Zilla::Plugin::Readme v6.012. Web-API-2.6/t/000755 000765 000024 00000000000 13567130466 012714 5ustar00levstaff000000 000000 Web-API-2.6/t/author-critic.t000644 000765 000024 00000000403 13567130466 015653 0ustar00levstaff000000 000000 #!perl BEGIN { unless ($ENV{AUTHOR_TESTING}) { print qq{1..0 # SKIP these tests are for testing by the author\n}; exit } } use strict; use warnings; use Test::Perl::Critic (-profile => "perlcritic.rc") x!! -e "perlcritic.rc"; all_critic_ok(); Web-API-2.6/t/author-eol.t000644 000765 000024 00000000744 13567130466 015165 0ustar00levstaff000000 000000 BEGIN { unless ($ENV{AUTHOR_TESTING}) { print qq{1..0 # SKIP these tests are for testing by the author\n}; exit } } use strict; use warnings; # this test was generated with Dist::Zilla::Plugin::Test::EOL 0.19 use Test::More 0.88; use Test::EOL; my @files = ( 'lib/Web/API.pm', 't/author-critic.t', 't/author-eol.t', 't/author-pod-coverage.t', 't/author-pod-syntax.t' ); eol_unix_ok($_, { trailing_whitespace => 1 }) foreach @files; done_testing; Web-API-2.6/t/author-pod-coverage.t000644 000765 000024 00000000536 13567130466 016760 0ustar00levstaff000000 000000 #!perl BEGIN { unless ($ENV{AUTHOR_TESTING}) { print qq{1..0 # SKIP these tests are for testing by the author\n}; exit } } # This file was automatically generated by Dist::Zilla::Plugin::PodCoverageTests. use Test::Pod::Coverage 1.08; use Pod::Coverage::TrustPod; all_pod_coverage_ok({ coverage_class => 'Pod::Coverage::TrustPod' }); Web-API-2.6/t/author-pod-syntax.t000644 000765 000024 00000000454 13567130466 016512 0ustar00levstaff000000 000000 #!perl BEGIN { unless ($ENV{AUTHOR_TESTING}) { print qq{1..0 # SKIP these tests are for testing by the author\n}; exit } } # This file was automatically generated by Dist::Zilla::Plugin::PodSyntaxTests. use strict; use warnings; use Test::More; use Test::Pod 1.41; all_pod_files_ok(); Web-API-2.6/lib/Web/000755 000765 000024 00000000000 13567130466 013734 5ustar00levstaff000000 000000 Web-API-2.6/lib/Web/API.pm000644 000765 000024 00000103636 13567130466 014714 0ustar00levstaff000000 000000 package Web::API; use 5.010001; use Mouse::Role; use experimental 'smartmatch'; # ABSTRACT: A Simple base module to implement almost every RESTful API with just a few lines of configuration our $VERSION = '2.6'; # VERSION use LWP::UserAgent; use HTTP::Cookies 6.04; use Data::Printer colored => 1; use XML::Simple; use URI::Escape::XS qw/uri_escape uri_unescape/; use JSON; use URI; use URI::QueryParam; use Carp; use Net::OAuth; use Data::Random qw(rand_chars); use Time::HiRes 'sleep'; $Net::OAuth::PROTOCOL_VERSION = Net::OAuth::PROTOCOL_VERSION_1_0A; our $AUTOLOAD; our %CONTENT_TYPE = ( json => 'application/json', js => 'application/json', xml => 'text/xml', ); requires 'commands'; has 'live_url' => ( is => 'rw', isa => 'Str', lazy => 1, builder => '_build_live_test_url', ); has 'test_url' => ( is => 'rw', isa => 'Str', lazy => 1, builder => '_build_live_test_url', ); has 'test' => ( is => 'rw', isa => 'Bool', default => sub { 0 }, ); has 'api_key' => ( is => 'rw', isa => 'Str', ); has 'user' => ( is => 'rw', isa => 'Str', ); has 'api_key_field' => ( is => 'rw', isa => 'Str', default => sub { 'key' }, ); has 'api_version' => ( is => 'rw', isa => 'Int', default => sub { 1 }, ); has 'mapping' => (is => 'rw'); has 'wrapper' => ( is => 'rw', clearer => 'clear_wrapper', ); has 'header' => ( is => 'rw', lazy => 1, default => sub { {} }, ); has 'auth_type' => ( is => 'rw', isa => 'Str', default => sub { 'none' }, ); has 'auth_header' => ( is => 'rw', isa => 'Str', default => sub { 'Authorization' }, ); has 'auth_header_token_format' => ( is => 'rw', isa => 'Str', default => sub { 'Token token=%s' }, ); has 'default_method' => ( is => 'rw', isa => 'Str', default => sub { 'GET' }, ); has 'extension' => ( is => 'rw', isa => 'Str', default => sub { '' }, ); has 'user_agent' => ( is => 'rw', isa => 'Str', default => sub { __PACKAGE__ . ' ' . $Web::API::VERSION }, ); has 'timeout' => ( is => 'rw', isa => 'Int', default => sub { 30 }, lazy => 1, ); has 'strict_ssl' => ( is => 'rw', isa => 'Bool', default => sub { 1 }, lazy => 1, ); has 'agent' => ( is => 'rw', isa => 'LWP::UserAgent', lazy => 1, required => 1, builder => '_build_agent', ); has 'retry_http_codes' => ( is => 'rw', isa => 'ArrayRef[Int]', ); has 'retry_errors' => ( is => 'rw', isa => 'ArrayRef[RegexpRef]', ); has 'retry_times' => ( is => 'rw', isa => 'Int', lazy => 1, default => sub { 3 }, ); has 'retry_delay' => ( is => 'rw', isa => 'Num', lazy => 1, default => sub { 1.0 }, ); has 'content_type' => ( is => 'rw', isa => 'Str', default => sub { 'text/plain' }, ); has 'incoming_content_type' => ( is => 'rw', isa => 'Str', ); has 'outgoing_content_type' => ( is => 'rw', isa => 'Str', ); has 'debug' => ( is => 'rw', isa => 'Bool', default => sub { 0 }, lazy => 1, ); has 'cookies' => ( is => 'rw', isa => 'HTTP::Cookies', default => sub { HTTP::Cookies->new }, ); has 'consumer_secret' => ( is => 'rw', isa => 'Str', ); has 'access_token' => ( is => 'rw', isa => 'Str', ); has 'access_secret' => ( is => 'rw', isa => 'Str', ); has 'signature_method' => ( is => 'rw', isa => 'Str', default => sub { 'HMAC-SHA1' }, lazy => 1, ); has 'encoder' => ( is => 'rw', isa => 'CodeRef', predicate => 'has_encoder', ); has 'decoder' => ( is => 'rw', isa => 'CodeRef', predicate => 'has_decoder', ); has 'oauth_post_body' => ( is => 'rw', isa => 'Bool', default => sub { 1 }, lazy => 1, ); has 'error_keys' => ( is => 'rw', isa => 'ArrayRef[Str]', ); has 'base_url' => ( is => 'rw', isa => 'Str', ); has 'json' => ( is => 'rw', isa => 'JSON', default => sub { my $js = JSON->new; $js->utf8; $js->allow_blessed; $js->convert_blessed; $js->allow_nonref; $js; }, ); has 'xml' => ( is => 'rw', isa => 'XML::Simple', lazy => 1, default => sub { XML::Simple->new( ContentKey => '-content', NoAttr => 1, KeepRoot => 1, KeyAttr => {}, ); }, ); has '_decoded_response' => ( is => 'rw', isa => 'Ref', clearer => 'clear_decoded_response', ); has '_response' => ( is => 'rw', isa => 'HTTP::Response', clearer => 'clear_response', ); sub _build_agent { my ($self) = @_; return LWP::UserAgent->new( agent => $self->user_agent, cookie_jar => $self->cookies, timeout => $self->timeout, keep_alive => 1, ssl_opts => { verify_hostname => $self->strict_ssl }, ); } sub _build_live_test_url { my ($self) = @_; return $self->base_url if $self->base_url; return; } sub nonce { return join('', rand_chars(size => 16, set => 'alphanumeric')); } sub log { ## no critic (ProhibitBuiltinHomonyms) my ($self, $msg) = @_; print STDERR caller() . ': ' . ($self->test ? '[test] ' : '[LIVE] ') . $msg . $/; return; } sub decode { my ($self, $content, $content_type) = @_; $self->log("decoding response from '$content_type'") if $self->debug; my $data; eval { if ($self->has_decoder) { $self->log('running custom decoder') if $self->debug; $data = $self->decoder->($content, $content_type); } else { given ($content_type) { when (/plain/) { chomp $content; $data = { text => $content }; } when (/urlencoded/) { foreach (split(/&/, $content)) { my ($key, $value) = split(/=/, $_); $data->{ uri_unescape($key) } = uri_unescape($value); } } when (/json/) { $data = $self->json->decode($content); } when (/(xml|html)/) { $data = $self->xml->XMLin($content, NoAttr => 0); } } } }; die("couldn't decode payload using $content_type: $@\n" . np($content)) if ($@ || ref \$content ne 'SCALAR'); $self->_decoded_response($data); return $data; } sub encode { my ($self, $options, $content_type) = @_; $self->log("encoding response to '$content_type'") if $self->debug; my $payload; eval { # custom encoder should only be run if called by Web::API otherwise we # end up calling it twice if ($self->has_encoder and caller(1) eq 'Web::API') { $self->log('running custom encoder') if $self->debug; $payload = $self->encoder->($options, $content_type); } else { given ($content_type) { when (/urlencoded/) { $payload .= uri_escape($_) . '=' . uri_escape($options->{$_}) . '&' foreach (keys %$options); chop($payload); } when (/json/) { $payload = $self->json->encode($options); } when (/xml/) { $payload = $self->xml->XMLout($options); } default { if (exists $options->{payload} and defined $options->{payload}) { $payload = '' . $options->{payload}; } } } } }; die("couldn't encode payload using $content_type: $@\n" . np(%$options)) if ($@ || ref \$payload ne 'SCALAR'); return $payload; } sub talk { my ($self, $command, $uri, $options, $query_keys, $content_type) = @_; my $method = uc($command->{method} || $self->default_method); my $oauth_req; # handle different auth_types given (lc $self->auth_type) { when ('basic') { $uri->userinfo($self->user . ':' . $self->api_key); } when ('header') { $self->header->{ $self->auth_header } = sprintf($self->auth_header_token_format, $self->api_key); } when ('hash_key') { my $api_key_field = $self->api_key_field; if ($self->mapping and not $command->{no_mapping}) { $self->log("mapping api_key_field: " . $self->api_key_field) if $self->debug; $api_key_field = $self->mapping->{$api_key_field} if $self->mapping->{$api_key_field}; } $options->{$api_key_field} = $self->api_key; } when ('get_params') { $uri->query_form( $self->mapping->{user} || 'user' => $self->user, $self->mapping->{api_key} || 'api_key' => $self->api_key, ); } when (/^oauth/) { my %opts = ( consumer_key => $self->api_key, consumer_secret => $self->consumer_secret, request_url => $uri, request_method => $method, signature_method => $self->signature_method, timestamp => time, nonce => $self->nonce, token => $self->access_token, token_secret => $self->access_secret, ); if ( $options and (($self->oauth_post_body and $method eq 'POST') or $method ne 'POST')) { $opts{extra_params} = { %$options, %{ $query_keys || {} } }; } $oauth_req = Net::OAuth->request("protected resource")->new(%opts); $oauth_req->sign; } default { $self->log( "WARNING: auth_type " . $self->auth_type . " not supported yet") unless (lc($self->auth_type) eq 'none'); } } # encode payload my $payload; if (keys %$options) { if ($method =~ m/^(GET|HEAD|DELETE)$/) { # TODO: check whether $option is a flat hashref unless ($self->auth_type eq 'oauth_params') { $uri->query_param_append($_ => $options->{$_}) for (keys %$options); } } else { $payload = $self->encode($options, $content_type->{out}); $self->log("send payload: $payload") if $self->debug; } } # append query keys to URI $uri->query_param_append($_ => $query_keys->{$_}) for keys %$query_keys; $uri = $oauth_req->to_url if ($self->auth_type eq 'oauth_params'); # build headers my %header = %{ $self->header }; if (exists $command->{headers} and ref $command->{headers} eq 'HASH') { %header = (%header, %{ $command->{headers} }); } my $headers = HTTP::Headers->new("Accept" => $content_type->{in}, %header); if ($self->debug) { $self->log("uri: $method $uri"); $self->log("extra headers: " . np(%header)) if (%header); $self->log("OAuth headers: " . $oauth_req->to_authorization_header) if ($self->auth_type eq 'oauth_header'); } # build request my $request = HTTP::Request->new($method, $uri, $headers); unless ($method =~ m/^(GET|HEAD|DELETE)$/) { $request->header("Content-type" => $content_type->{out}); $request->content($payload); } # oauth POST if ( $options and ($method eq 'POST') and ($self->auth_type =~ m/^oauth/) and $self->oauth_post_body) { $request->content($oauth_req->to_post_body); } # oauth_header $request->header(Authorization => $oauth_req->to_authorization_header) if ($self->auth_type eq 'oauth_header'); # add session cookies $self->agent->cookie_jar($self->cookies); # do the actual work return $self->request($request); } sub map_options { my ($self, $options, $command) = @_; my %opts; # first include default attributes %opts = %{ $command->{default_attributes} } if exists $command->{default_attributes}; # then map everything in $options, overwriting default_attributes if necessary if ($self->mapping and not $command->{no_mapping}) { $self->log("mapping hash:\n" . np(%{ $self->mapping })) if $self->debug; # do the key and value mapping of options hash and overwrite defaults foreach my $key (keys %$options) { my ($newkey, $newvalue); $newkey = $self->mapping->{$key} if ($self->mapping->{$key}); $newvalue = $self->mapping->{ $options->{$key} } if ($options->{$key} and $self->mapping->{ $options->{$key} }); $opts{ $newkey || $key } = $newvalue || $options->{$key}; } # and write everything back to $options $options = \%opts; } else { $options = { %opts, %$options }; } return $options; } sub check_mandatory { my ($self, $options, $mandatory) = @_; $self->log("mandatory keys:\n" . np(@$mandatory)) if $self->debug; my @missing_attrs; foreach my $attr (@$mandatory) { push(@missing_attrs, $attr) unless $self->key_exists($attr, $options); } die 'mandatory attributes for this command missing: ' . join(', ', @missing_attrs) . $/ if @missing_attrs; return; } sub key_exists { my ($self, $path, $hash) = @_; my @bits = split /\./, $path; my $node = $hash; return $node if @bits == grep { ref $node eq "HASH" && exists $node->{$_} && ($node = $node->{$_} // {}) } @bits; return; } sub wrap { my ($options, $wrapper, $content_type) = @_; if (ref $wrapper eq 'ARRAY') { # XML needs wrapping into extra array ref layer to make XML::Simple # behave correctly if ($content_type =~ m/xml/) { $options = { $_ => [$options] } for (reverse @$wrapper); } else { $options = { $_ => $options } for (reverse @$wrapper); } } elsif (defined $wrapper) { $options = { $wrapper => $options }; } return $options; } sub request { my ($self, $request) = @_; my $response; my $error; if ( ($self->retry_http_codes and scalar(@{ $self->retry_http_codes })) or ($self->retry_errors and scalar(@{ $self->retry_errors }))) { my $times = $self->retry_times; my $n = 0; while ($times-- > 0) { $n++; $self->log("try: $n/" . $self->retry_times . ' delay: ' . $self->retry_delay . 's') if $self->debug; $response = eval { $self->agent->request($request) }; $error = $@; # if the user agent died there was a connection issue, definitely retry those unless ($error) { $self->_response($response); $self->log("recv payload: " . $response->decoded_content) if $self->debug; return $response unless $self->needs_retry($response, $request->header('Accept')); } sleep $self->retry_delay if $times; # Do not sleep in last time } } else { $response = eval { $self->agent->request($request) }; $error = $@; $self->log("recv payload: " . $response->decoded_content) if $response and $self->debug; } $self->_response($response); die $error if $error; return $response; } sub needs_retry { my ($self, $response, $content_type) = @_; $self->log("response code was: " . $response->code) if $self->debug; return 1 if $response->code ~~ $self->retry_http_codes; if ( $self->retry_errors and scalar(@{ $self->retry_errors }) and $self->error_keys and scalar(@{ $self->error_keys })) { # we need to decode the response content to be able to find a custom # error field my $content = $self->decode($response->decoded_content, ($response->header('Content-Type') || $content_type)); my $error = $self->find_error($content); return unless $error; return 1 if map { $error =~ $_ } @{ $self->retry_errors }; } return; } sub find_error { my ($self, $content) = @_; for (@{ $self->error_keys || [] }) { $self->log("checking for error at ($_)") if $self->debug; my $node = $self->key_exists($_, $content); if ($node) { $self->log("found error: '$node' at ($_)") if $self->debug; return $node; } } return; } sub format_response { my ($self, $response, $ct, $error) = @_; my $answer; if ($response) { # collect response headers my $response_headers; $response_headers->{$_} = $response->header($_) foreach ($response->header_field_names); # decode content if necessary unless ($self->_decoded_response) { if ( defined $response->decoded_content and length($response->decoded_content) > 0 and $response->decoded_content =~ m/\S/) { $self->_decoded_response( eval { $self->decode($response->decoded_content, ($response_headers->{'Content-Type'} || $ct)); }); $error ||= $@; } } # search for and expose errors $error ||= $self->find_error($self->_decoded_response); $answer = { header => $response_headers, code => $response->code, content => $self->_decoded_response, raw => $response->content, cookies => $self->cookies->get_cookies($self->base_url), }; unless ($response->is_success || $response->is_redirect) { $error ||= $response->status_line; } } if ($error) { chomp($error); $self->log("ERROR: $error"); $answer->{error} = $error; } return $answer; } sub build_uri { my ($self, $command, $options, $path) = @_; my $uri = URI->new($self->base_url); my $p = $uri->path; if ($path) { $p .= '/' . $path; # parse all mandatory ID keys from URI path # format: /path/with/some/:id/and/:another_id/fun.js my @mandatory = ($path =~ m/:(\w+)/g); # and replace placeholders foreach my $key (@mandatory) { die "required {$key} option missing\n" unless (exists $options->{$key}); my $encoded_option = uri_escape(delete $options->{$key}); $p =~ s/:$key/$encoded_option/gex; } } else { $p .= "/$command"; } $p .= '.' . $self->extension if ($self->extension); $uri->path($p); return $uri; } sub build_content_type { my ($self, $command) = @_; return { in => $command->{incoming_content_type} || $command->{content_type} || $CONTENT_TYPE{ $self->extension } || $self->incoming_content_type || $self->content_type, out => $command->{outgoing_content_type} || $command->{content_type} || $self->outgoing_content_type || $self->content_type, }; } sub DESTROY { } sub AUTOLOAD { my ($self, %options) = @_; $self->clear_decoded_response; $self->clear_response; $self->base_url($self->test ? $self->test_url : $self->live_url); # sanity checks die "Attribute (base_url) is required\n" unless $self->base_url; if ($self->auth_type =~ m/^oauth_/) { for (qw(consumer_secret access_token access_secret)) { die "Attribute ($_) is required\n" unless $self->$_; } } my ($command) = $AUTOLOAD =~ /([^:]+)$/; my $ct; my $response = eval { die "unknown command: $command\n" unless (exists $self->commands->{$command}); my $options = \%options; # construct URI my $uri = $self->build_uri($command, $options, $self->commands->{$command}->{path}); # first select the right content types for encoding/decoding $ct = $self->build_content_type($self->commands->{$command}); # then map options if necessary $options = $self->map_options($options, $self->commands->{$command}, $ct->{in}) if (((keys %$options) and ($ct->{out} =~ m/(xml|json|urlencoded)/)) or (exists $self->commands->{$command}->{default_attributes}) or (exists $self->commands->{$command}->{mandatory})); # then check existence of mandatory attributes $self->check_mandatory($options, $self->commands->{$command}->{mandatory}) if exists $self->commands->{$command}->{mandatory}; # then extract query keys from options to prevent them being wrapped # in the next step my $query_keys; foreach my $key (keys %$options) { $query_keys->{$key} = delete $options->{$key} if $key ~~ $self->commands->{$command}->{query_keys}; } # finally wrap all options in wrapper key(s) if requested my $method = uc($self->commands->{$command}->{method} || $self->default_method); $options = wrap($options, $self->commands->{$command}->{wrapper} || $self->wrapper, $ct->{in}) unless ($method =~ m/^(GET|HEAD|DELETE)$/); $self->log("options:\n" . np(%$options)) if $self->debug; # do the talking return $self->talk($self->commands->{$command}, $uri, $options, $query_keys, $ct); }; return $self->format_response($self->_response, $ct->{in}, $@); } 1; # End of Web::API __END__ =pod =encoding UTF-8 =head1 NAME Web::API - A Simple base module to implement almost every RESTful API with just a few lines of configuration =head1 VERSION version 2.6 =head1 SYNOPSIS B as of version 2.1 C is enabled by default for obvious security reasons, this may break your current library implementation, sorry. Implement the RESTful API of your choice in 10 minutes, roughly. package Net::CloudProvider; use Mouse; with 'Web::API'; our $VERSION = "0.1"; has 'commands' => ( is => 'rw', default => sub { { list_nodes => { method => 'GET' }, node_info => { method => 'GET', require_id => 1 }, create_node => { method => 'POST', default_attributes => { allowed_hot_migrate => 1, required_virtual_machine_build => 1, cpu_shares => 5, required_ip_address_assignment => 1, primary_network_id => 1, required_automatic_backup => 0, swap_disk_size => 1, }, mandatory => [ 'label', 'hostname', 'template_id', 'cpus', 'memory', 'primary_disk_size', 'required_virtual_machine_build', 'cpu_shares', 'primary_network_id', 'required_ip_address_assignment', 'required_automatic_backup', 'swap_disk_size', ] }, update_node => { method => 'PUT', require_id => 1 }, delete_node => { method => 'DELETE', require_id => 1 }, start_node => { method => 'POST', require_id => 1, post_id_path => 'startup', }, stop_node => { method => 'POST', require_id => 1, post_id_path => 'shutdown', }, suspend_node => { method => 'POST', require_id => 1, post_id_path => 'suspend', }, }; }, ); sub commands { my ($self) = @_; return $self->commands; } sub BUILD { my ($self) = @_; $self->user_agent(__PACKAGE__ . ' ' . $VERSION); $self->live_url('https://ams01.cloudprovider.net/virtual_machines'); $self->content_type('application/json'); $self->extension('json'); $self->wrapper('virtual_machine'); $self->mapping({ os => 'template_id', debian => 1, id => 'label', disk_size => 'primary_disk_size', }); return $self; } 1; later use as: use Net::CloudProvider; my $nc = Net::CloudProvider->new(user => 'foobar', api_key => 'secret'); my $response = $nc->create_node({ id => 'funnybox', hostname => 'node.funnybox.com', os => 'debian', cpus => 2, memory => 256, disk_size => 5, allowed_hot_migrate => 1, required_virtual_machine_build => 1, cpu_shares => 5, required_ip_address_assignment => 1, }); =head1 ATTRIBUTES =head2 commands most important configuration part of the module which has to be provided by the module you are writing. the following keys are valid/possible: method path mandatory default_attributes headers extension content_type incoming_content_type outgoing_content_type wrapper query_keys require_id (deprecated, use path) pre_id_path (deprecated, use path) post_id_path (deprecated, use path) the request path for commands is being build as: $base_url/$path.$extension an example for C: path => 'users/:user_id/labels' this will add C to the list of mandatory keys for this command automatically. =head2 live_url (required) get/set base URL to API, can include paths =head2 test_url (optional) get/set base URL for test system if applicable =head2 test (optional) get/set boolean to run against base URL from test system or live system =head2 api_key (required in most cases) get/set API key (also used as basic auth password) =head2 user (optional) get/set API username/account name =head2 api_key_field (optional) get/set name of the hash key that has to hold the C e.g. in POST content payloads =head2 api_version (optional) get/set API version to be used default: 1 =head2 mapping (optional) supply mapping table, hashref of format { "key" => "value", ... } =head2 wrapper (optional) get/set name of the key that is used to wrap all options of a command in. unfortunately some APIs increase the depth of a hash by wrapping everything into a single key (who knows why...), which means this: $wa->command(%options); turns C<%options> into: { wrapper => \%options } before encoding and sending it off. =head2 header (optional) get/set custom headers sent with every request =head2 auth_type get/set authentication type. currently supported are only 'basic', 'header', 'hash_key', 'get_params', 'oauth_header', 'oauth_params' or 'none' default: none =head2 auth_header (optional) get/set the name of the header used for Authorization credentials default: Authorization =head2 auth_header_token_format get/set format of the auth_header token. default: 'Token token=%s' =head2 default_method (optional) get/set default HTTP method default: GET =head2 extension (optional) get/set file extension, e.g. 'json' =head2 user_agent (optional) get/set User Agent String default: "Web::API $VERSION" =head2 timeout (optional) get/set L timeout =head2 strict_ssl (optional) enable/disable strict SSL certificate hostname checking as a convenience alternatively you can supply your own LWP::Useragent compatible agent for the C attribute. default: true =head2 agent (optional) get/set L object =head2 retry_http_codes (optional) get/set array of HTTP response codes that trigger a retry of the request =head2 retry_errors (optional) define an array reference of regexes that should trigger a retry of the request if matched against an error found via one of the C =head2 retry_times (optional) get/set number of times a request will be retried at most default: 3 =head2 retry_delay (optional) get/set delay to wait between retries. accepts float for millisecond support. default: 1.0 =head2 content_type (optional) global content type, which is used for in and out going request/response headers and to encode and decode the payload if no other more specific content types are set, e.g. C, C or content types set individually per command attribute. default: 'text/plain' =head2 incoming_content_type (optional) default: undef =head2 outgoing_content_type (optional) default: undef =head2 debug (optional) enable/disabled debug logging default: false =head2 cookies (optional) this is used to store and retrieve cookies before and after requests were made to keep authenticated sessions alive for the time this object exists in memory you can add your own cookies to be send with every request. See L for more information. default: HTTP::Cookies->new() =head2 consumer_secret (required for all oauth_* auth_types) default: undef =head2 access_token (required for all oauth_* auth_types) default: undef =head2 access_secret (required for all oauth_* auth_types) default: undef =head2 signature_method (required for all oauth_* auth_types) default: undef =head2 encoder (custom options encoding subroutine) Receives C<\%options> and C as the only 2 arguments and has to return a single scalar. default: undef =head2 decoder (custom response content decoding subroutine) Receives C and C as the only 2 scalar arguments and has to return a single hash reference. default: undef =head2 oauth_post_body (required for all oauth_* auth_types) enable/disable adding of command options as extra parameters to the OAuth request generation and therefor be included in the OAuth signature calculation. default: true =head2 error_keys get/set list of array keys that will be search for in the decoded response data structure. the same format as for mandatory keys is supported: some.deeply.nested.error.message will search for an error message at $decoded_response->{some}->{deeply}->{nested}->{error}->{messsage} and if the key exists and its value is defined it will be provided as C<$response->{error}> and matched against all regexes from the `retry_errors` array ref if provided to trigger a retry on particular errors. =head1 INTERNAL SUBROUTINES/METHODS =head2 nonce generates new OAuth nonce for every request =head2 log =head2 decode =head2 encode =head2 talk =head2 map_options =head2 check_mandatory =head2 key_exists =head2 wrap =head2 request retry request with delay if C is set, otherwise just try once. =head2 needs_retry returns true if the HTTP code or error found match either C or C respectively. returns false otherwise. if C are defined it will try to decode the response content and store the decoded structure internally so we don't have to decode again at the end. needs the last response object and the 'Accept' content type header from the request for decoding. =head2 find_error go through C and find a potential error message in the decoded/parsed response and return it. =head2 format_response =head2 build_uri =head2 build_content_type configure in/out content types order of precedence: 1. per command C / C 2. per command general C 3. content type based on file path extension (only for incoming) 4. global C / C 5. global general C =head2 DESTROY catch DESTROY call and tear down / clean up if necessary at this point there is nothing to do though. This prevents AUTOLOAD from logging an unknown command error message =head2 AUTOLOAD magic install a method for each new command and call it in an C to catch exceptions and set an error in a unified way. =head1 BUGS Please report any bugs or feature requests on GitHub's issue tracker L. Pull requests welcome. =head1 SUPPORT You can find documentation for this module with the L command. perldoc Web::API You can also look for information at: =over 4 =item * GitHub repository L =item * MetaCPAN L =item * AnnoCPAN: Annotated CPAN documentation L =item * CPAN Ratings L =back =head1 SEE ALSO L, L, L =head1 AUTHOR Tobias Kirschstein =head1 COPYRIGHT AND LICENSE This software is Copyright (c) 2013 by Tobias Kirschstein. This is free software, licensed under: The (three-clause) BSD License =cut