NAME
WebService::NFSN - Client for the NearlyFreeSpeech.NET API
VERSION
This document describes version 1.04 of WebService::NFSN, released April 20, 2024 as part of WebService-NFSN version 1.04.
SYNOPSIS
use WebService::NFSN;
my $nfsn = WebService::NFSN->new($USER, $API_KEY);
my $balance = $nfsn->account($ACCOUNT_ID)->balance;
$nfsn = WebService::NFSN->new; # Get credentials from ~/.nfsn-api
DESCRIPTION
WebService::NFSN is a client library for NearlyFreeSpeech.NET's member API. It is only useful to people who have websites hosted at NearlyFreeSpeech.NET.
Much of this documentation was adapted from the original API documentation at https://members.nearlyfreespeech.net/wiki/API.
INTERFACE
$nfsn = WebService::NFSN->new( [$USER, $API_KEY] )
-
This constructs a new API manager object.
$USER
is your NFSN member login. You can get your$API_KEY
by making a free Assistance Request at https://members.nearlyfreespeech.net/support/request. (Select "Request an API key" on that page.)If you call new without parameters, it will look for a file named .nfsn-api in the current directory and (if not found there) in your home directory. The file must contain a JSON object that defines the keys
login
andapi-key
. Any additional keys are ignored.Example .nfsn-api file:
{ "login": "USER", "api-key": "API_KEY" }
$nfsn->account($ACCOUNT_ID)
-
Returns a WebService::NFSN::Account object for the specified account number (a string like
'A1B2-C3D4E5F6'
). $nfsn->dns($DOMAIN)
-
Returns a WebService::NFSN::DNS object for the specified domain (like
'example.com'
). $nfsn->email($DOMAIN)
-
Returns a WebService::NFSN::Email object for the specified domain.
$nfsn->member( [$USER] )
-
Returns a WebService::NFSN::Member object for the specified member login. If
$USER
is omitted, it defaults to the member login that was passed tonew
. $nfsn->site($SHORT_NAME)
-
Returns a WebService::NFSN::Site object for the specified site (identified by its short name).
$nfsn->last_response
-
Returns the HTTP::Response object containing the raw response from the last query sent to API.NearlyFreeSpeech.NET. You shouldn't normally need this, but it may be handy for debugging.
DIAGNOSTICS
WebService::NFSN::HTTPError
Most errors you might get from WebService::NFSN are Exception::Class based objects. WebService::NFSN::HTTPError is the abstract base class for these errors. The request
field contains the HTTP::Request object that failed, and the response
field contains the original HTTP::Response object.
WebService::NFSN throws errors from two classes derived from WebService::NFSN::HTTPError:
WebService::NFSN::LWPError
If WebService::NFSN cannot get a response from the NFSN server, it throws an error of class WebService::NFSN::LWPError. Examine the response
field for details.
WebService::NFSN::NFSNError
If the NFSN server returns an error response, it becomes an error of class WebService::NFSN::NFSNError. The error
and debug
fields contain the values received from NFSN. Any additional fields returned by NFSN are available in the nfsn
field (which is a hash reference). You can also examine the original response
.
Possible errors include:
The API request could not be authenticated
-
You're probably using the wrong member login or API key.
The authentication timestamp is out of range
-
The clocks of the NFSN API server and your computer need to be synchronised to within 5 seconds, and they aren't. You may need to set up NTP on your computer.
Simple Errors
The following errors do not use Exception::Class, because you should never see them unless you have an error in your program. They are classified like Perl's built-in diagnostics (perldiag):
(S) A severe warning
(F) A fatal error (trappable)
Missing required "%s" parameter for %s
-
(F) You failed to supply a parameter required by the method you called.
"%s" is not a parameter of %s
-
(S) You supplied a parameter not recognized by the method you called. This is only a warning; the parameter is still passed along to NFSN (in case it was added in a newer version of the API).
%s is read-only
-
(F) You tried to modify a read-only property.
%s is write-only
-
(F) You tried to read a write-only property.
Can't open %s
-
(F) There was an error when opening the .nfsn-api file.
Error closing %s
-
(F) There was an error when closing the .nfsn-api file.
Error parsing .nfsn-api: %s
-
(F) .nfsn-api did not contain valid JSON.
.nfsn-api did not contain a JSON object
-
(F) .nfsn-api did not contain a JSON object (it must begin with
{
). .nfsn-api did not define %s
-
(F) .nfsn-api must include the keys
login
andapi-key
. You must supply a login
-
(F) You didn't pass a member login to the constructor, and no .nfsn-api file was found.
You must supply an API key
-
(F) You passed a login name to the constructor, but no API key.
Unable to locate .nfsn-api
-
(S) You didn't pass login credentials to the constructor, and it couldn't find a .nfsn-api file to load.
CONFIGURATION AND ENVIRONMENT
WebService::NFSN has an optional configuration file named .nfsn-api. See the constructor for the details. The home directory is specified by $ENV{HOME}
.
DEPENDENCIES
Digest::SHA, Exception::Class, JSON::XS, LWP (requires https
support), and URI. These are all available from CPAN.
You need at least LWP version 6.00 in order to verify the server's certificate. Earlier versions of LWP are vulnerable to a man-in-the-middle attack.
INCOMPATIBILITIES
None reported.
BUGS AND LIMITATIONS
No bugs have been reported.
AUTHOR
Christopher J. Madsen <perl AT cjmweb.net>
Please report any bugs or feature requests to <bug-WebService-NFSN AT rt.cpan.org>
or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=WebService-NFSN.
You can follow or contribute to WebService-NFSN's development at https://github.com/madsen/webservice-nfsn.
COPYRIGHT AND LICENSE
This software is copyright (c) 2024 by Christopher J. Madsen.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
DISCLAIMER OF WARRANTY
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.