Igor Zinovyev > Eve > Eve::HttpResource::Graph

Download:
Eve-0.06.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Source  

NAME ^

Eve::HttpResource::Graph - a base class for the Graph API node HTTP resources.

SYNOPSIS ^

    package Eve::HttpResource::SomeGraphResource;

    use parent qw(Eve::HttpResource::Graph);

    sub _read {
        # some object's hash is returned here
    }

    sub _get_connections {
        # some connections hash is returned here
    }

    sub _get_fields {
        # some object fields hash is returned here
    }

    sub _get_type {
        # a required type string is returned here
    }

    1;

DESCRIPTION ^

Eve::HttpResource::Graph is an HTTP resource based class providing an automation of the Facebook like Graph API node/connection functionality.

Methods _read(), _publish(), _remove(), _get_connections(), _get_fields(), _get_type(), _get_actions() and _get_id_alias_hash() could be overriden by the class derivatives. When not overriden these methods except _get_connections() and _get_fields throw the exception Eve::Exception::Http::405MethodNotAllowed. _get_type throws a Eve::Error::NotImplemented exception which means it must be overridden to be used. Inside the described above methods class attributes _request, _response, _session, _event_map and _dispatcher can be found.

All methods are passed the list of named matched URI parameters as arguments. The following example illustrates the usage of named arguments in a resource that is bound to the http://example.com/:named/:another pattern URI:

    my ($self, %arg_hash) = @_;
    Eve::Support::arguments(\%arg_hash, my ($named, $another));

If the metadata query string parameter is specified then the metadata section is added to the result. This section always contains the object's type returned by the _get_type method, and if present, the object's connections returned by the _get_connections() method, the object's fields returned by the _get_fields method and the object's actions returned by the _get_actions() method.

If the request method is POST and the query string is supplied with method=delete then it behaves just like the DELETE method is requested. If other value is passed to the method then the exception Eve::Exception::Http::400BadRequest is thrown.

If Eve::Exception::Privilege is thrown in the user code the exception Eve::Exception::Http::403Forbidden is rethrown.

Note that the resource must be bound with the id placeholder. The _id attribute is representing it. If _get_id_alias_hash() is redefined you can use ID aliases in URI according to the hash keys.

Object deletion requests must use the deleted object's node URI. In case a connection with no public ID is deleted, the request must use the respective object connection URI.

Constructor arguments

request

an HTTP request object

response

an HTTP response object

session_constructor

a reference to a subroutine accepting the session id argument and returning a session object

dispatcher

an HTTP dispatcher object

json

a JSON encoder object.

METHODS ^

init()

_read()

This method is called when the graph node or connection is requested with the GET method.

Returns

It is expected to return a data hash reference that will be automatically converted to a required textual representation and returned to the client

Throws

Eve::Exception::Http::405MethodNotAllowed

When a method is used without being overridden in a descendant class.

_publish()

This method is called when the graph node or connection is requested with the POST method.

Returns

It is expected to return a data hash reference that will be automatically converted to a required textual representation and returned to the client

Throws

Eve::Exception::Http::405MethodNotAllowed

When a method is used without being overridden in a descendant class.

_remove()

This method is called when the graph node or connection is requested with the DELETE method or when the POST method is used in conjunction with a method=delete query string parameter..

Returns

It is expected to return a data hash reference that will be automatically converted to a required textual representation and returned to the client

Throws

Eve::Exception::Http::405MethodNotAllowed

When a method is used without being overridden in a descendant class.

_get_connections()

This method is called when the metadata parameter is recieved in the request. Overriding this method is optional.

Returns

It is expected to return a connection hash reference that will be automatically converted to a required textual representation and returned to the client.

_get_fields()

This method is called when the metadata parameter is recieved in the request. Overriding this method is optional.

Returns

It is expected to return a fields hash reference that will be automatically converted to a required textual representation and returned to the client.

_get_actions()

This method is called when the metadata parameter is recieved in the request. Overriding this method is optional.

Returns

It is expected to return an actions hash reference with action keys as keys and action names as values that will be automatically converted to a required textual representation and returned to the client.

_get_type()

This method is called when the metadata parameter is recieved in the request.

Returns

It is expected to return a type string that will be automatically converted to a required textual representation and returned to the client.

Throws

Eve::Error::NotImplemented

When a method is used without being overridden in a descendant class.

_get_alias_hash()

This method is called when the graph HTTP resource processes the pattern placeholder matches from a request URI. A hash of aliases for an id can be specified in this method. For example, if an id in the URI is specified as an alias keyword, it can be replaced with a real identifier by returning this hash reference:

    return {'alias' => $some_service->get_parameter(name => 'id')};

Returns

It is expected to return a reference to a hash of aliases for an identifier.

Throws

Eve::Error::NotImplemented

When a method is used without being overridden in a descendant class.

SEE ALSO ^

Eve::HttpResource
Eve::Exception

LICENSE AND COPYRIGHT ^

Copyright 2012 Igor Zinovyev.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

AUTHOR ^

Sergey Konoplev
syntax highlighting: