/ 
Protocol-Notifo-0.004
River stage one • 2 direct dependents • 4 total dependents
/ Protocol::Notifo

NAME

Protocol::Notifo - utilities to build requests for the notifo.com service

VERSION

version 0.004

SYNOPSIS

## Reads user and api_key from configuration file
my $pn = Protocol::Notifo->new;

## Use a particular user and api_key, overrides configuration file
my $pn = Protocol::Notifo->new(user => 'me', api_key => 'my_key');

my $req = $pn->send_notification(msg => 'Hi!');

.... send $req, get a response back ....

my $res = $pn->parse_response($response_http_code, $response_body);

.... do stuff with $res ....

DESCRIPTION

This module provides an API to prepare requests to the http://notifo.com/ service.

The module doesn't actually execute the HTTP request. It only prepares all the information required for such request to be performed. As such this module is not to be used by end users, but by writters of notifo.com API clients.

If you are an end-user and want to call the API, you should look into the modules WebService::Notifo and AnyEvent::WebService::Notifo.

This module supports both the User API and the Service API. Differences between the behaviour of the two are noted in this documentation where relevant.

You need a notifo.com account to be able to use this module. The account will give you access to an API username, and an API key. Both are required arguments of our constructors.

The module also supports a configuration file. See config_file() to learn which configuration file will be loaded automatically, if found.

For all the details of the notifo.com API, check out the site https://api.notifo.com/.

CONSTRUCTORS

new

Creates new Protocol::Notifo object.

It first tries to load default values from a configuration file. If you set the environment variable NOTIFO_CFG, it will try that. If not, it will default to File::HomeDir->my_home(). See section "CONFIGURATION FILE" for the format of those files.

You can also pass a hash of options, that will override the defaults set by the configuration file. The following options are accepted:

user

The API username.

api_key

The API key.

Values for this two options can be found in the user settings page of the notifo site.

METHODS

parse_response

Accepts a hash with response information. The following fields must be present:

http_response_code

The HTTP code of the response message.

http_status_line

The HTTP status line of the response message.

http_body

The response content.

Other fields might be passed, they will be ignored and returned in the other field of the return value.

This method parses the content, adds the HTTP response code and returns a hashref with all the fields.

The following fields are present on all responses:

status

A string, either success or error.

http_response_code

The HTTP code of the response message.

http_status_line

The HTTP status line of the response message.

response_code

A notifo.com integer response code.

response_message

A text description of the response. Specially useful when status is error.

other

All parse_response() other parameters.

send_notification

Prepares a request for the send_notification API.

Accepts a hash with options. The following options are supported:

msg

The notification message. This parameter is required.

to

The destination user. If the API username/key pair used is of a User account, then this parameter is ignored and can be safelly ommited.

A User account can only send notifications to itself. A Service account can send notifications to all his subscribed users.

label

A label describing the application that is sending the notification. With Service accounts, this option is ignored and the Service Name is used.

title

The title or subject of the notification.

uri

The URL for the event. On some clients you can click the notification and jump to this URL.

The return value is a hashref with all the relevant information to perform the HTTP request: the url and the method to use, the Authorization header, and the query form fields.

An example:

url    => URI->new("https://api.notifo.com/v1/send_notification"),
method => "POST",
args   => {
  label => "l",
  msg   => "hello",
  title => "t",
  to    => "to"
},
headers => [
  "Authorization"  => "Basic bWU6bXlfa2V5",
  "Content-Type"   => "application/x-www-form-urlencoded",
  "Content-Length" => 31,
],
body => "msg=hello&to=to&title=t&label=l",

The following keys are always present in the hashref:

url

The URI object representing the URL where the HTTP request should be sent to.

method

The HTTP method to use.

args

A hashref with all the URL query form fields and values.

headers

A hashref with all the headers to include in the HTTP request.

body

The args in application/x-www-form-urlencoded form, can be used as the body of the HTTP request.

config_file

Returns the configuration file that this module will attempt to use.

CONFIGURATION FILE

The configuration file is line based. Empty lines os just spaces/tabs, or lines starting with # are ignored.

All other lines are parsed for commands, in the form command separator value. The separator can be a = or a :.

See the new() constructor for the commands you can use, they are the same ones as the accepted options.

TODO

Future versions of this module will implement the other APIs:

subscribe_user
send_message

Patches welcome.

AUTHOR

Pedro Melo <melo@simplicidade.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2010 by Pedro Melo.

This is free software, licensed under:

The Artistic License 2.0