NAME

WWW::GoDaddy::REST::Resource - Represent a REST resource

SYNOPSIS

$client = WWW::GoDaddy::REST->new(...);

$resource = WWW::GoDaddy::REST::Resource->new({
  client => $client,
  fields => {
      'type'  => 'automobile',
      'id'    => '1001',
      'make'  => 'Tesla',
      'model' => 'S'
      'links' => {
          'self'    => 'https://example.com/v1/automobiles/1001',
          'schemas' => 'https://example.com/v1/schemas'
      },
      'actions' => {
          'charge' => 'https://example.com/v1/automobiles/1001?charge'
      }
      # ...
      # see: https://github.com/godaddy/gdapi/blob/master/specification.md
  },
});

$resource->f('id'); # get 1001
$resource->f('id','2000'); # set to 2000 and return 2000

# follow a link in links section
$schemas_resource = $resource->follow_link('schemas');

# perform an action in the actions section
$result_resource  = $resource->do_action('charge',{ 'with' => 'quick_charger' });

DESCRIPTION

Base class used to represent a REST resource.

CLASS METHODS

new

Given a hash reference of "ATTRIBUTES" and values, return a new instance of this object.

It is likely more important that you use the new_subclassed class method.

Example:

my $resource = WWW::GoDaddy::REST::Resource->new({
  client => WWW::GoDaddy::REST->new(...),
  fields => {
      id => '...',
      ...
  },
});

new_subclassed

This takes the same paramegers as new and is the preferred construction method. This tries to find the appropriate subclass of WWW::GoDaddy::REST::Resource and passes along the paramegers to the new method of that subclass instead.

See also: new

find_implementation

Given a list of schema type names, find the best implementation sub class.

Returns the string of the class name. If no good subclass candidate is found, returns undef.

Example:

find_implementation( 'schema' );
# WWW::GoDaddy::REST::Schema

register_implementation

Register a subclass handler for a schema type given a schema name and the name of a WWW::GoDaddy::REST::Resource subclass.

This can take as many schema => resource class pairs as you want.

Example:

WWW::GoDaddy::REST::Resource->register_subclass( 'account' => 'My::AccountRes' );
WWW::GoDaddy::REST::Resource->register_subclass( 'foo' => 'Bar', 'baz' => 'Buzz' );

ATTRIBUTES

client

Instance of WWW::GoDaddy::REST associated with the resource.

fields

Hash reference containing the raw data for the underlying resource.

Several methods delegate to this underlying structure such as f, and field.

http_response

Optionally present instance of an HTTP::Response object so that you can inspect the HTTP information related to the resource.

METHODS

f

Get or set a field by name. You may also use the longer name field.

When performing a set, it also returns the new value that was set.

Example:

$res->f('field_name');       # get
$res->f('field_name','new'); # set

f_as_resources

Get a field by name. If it is a resource, this will turn it into an object instead of giving you the raw hash reference as the return value.

Note, if the field is a 'map' or 'array' of resources, every item in those lists will be 'resourcified'.

If this is not a resource, then it does return the raw value.

Example:

# return value is a WWW::GoDaddy::REST::Resource, not a hash ref
$driver = $car->f('driver');

See f if you want the raw value. This will return the raw value, if the value does not look like a resource.

field

Get or set a field by name. You may also use the shorter name f.

When performing a set, it also returns the new value that was set.

Example:

$res->field('field_name');       # get
$res->fieldf('field_name','new'); # set

save

Does a PUT at this resources URI. Returns a new resource object.

Example:

$r2 = $r1->save();

delete

Does a DELETE on this resource. Returns a new resource object. This return value likely is only useful to get at the http_response attribute.

do_action

Does a POST with the supplied data on the action URL with the given name.

If the action with the provided name does not exist, this method will die. See also: action and actions

Example:

$r2 = $r1->do_action('some_action',{ a => 'a_v' });

follow_link

Gets the resource by following the link URL with the provided name.

If the link with the provided name does not exist, this method will die. See also: link and link

Example:

$r2 = $r1->follow_link('some_link');

id

Return the id of this instance

type

Return the name of the schema type that this object belongs to.

type_fq

Return the full URI to the schema type that this object belongs to.

resource_type

Return the name of the schema type that this collection's objects belong to.

resource_type_fq

Return the full URI to the schema type that this collection's objects belong to.

schemas_url

Returns the URL for the schema collection. This differs from the client schemas_url method since it has more places to look for hints of the schemas collection url (headers, json response etc).

Example:

$r->schemas_url();

schema

Find and return the WWW::GoDaddy::REST::Schema object that this is.

link

Return the link URL for the given name or undef if it does not exist.

Example:

# https://example.com/v1/thing/...
$r->link('self');
# 'https://example.com/v1/me/1'

links

Return the hashref that contains the link => url information

Example:

$r->links();
# {
#     'self'      => 'https://example.com/v1/me/1',
#     'some_link' => 'https://example.com/v1/me/1/some_link'
# }

action

Return the action URL for the given name.

Example:

$r->action('custom_action');
# https://example.com/v1/thing/1001?some_action

actions

Return the hashref that contains the action => url information

Example:

$r->actions();
# {
#     'custom_action' => 'https://example.com/v1/thing/1001?some_action'
# }

items

Returns a list of resources that this resource contains. This implementation simply returns a list of 'self'. It is here to be consistent with the implementation found in WWW::GoDaddy::REST::Collection.

Example:

@items = $resource->items();

TO_JSON

Returns a hashref that represents this object. This exists to make using the JSON module more convenient. This does NOT return a JSON STRING, just a perl data structure.

See to_string.

to_string

Returns a JSON string that represents this object. This takes an optional parameter, "pretty". If true, the json output will be prettified. This defaults to false.

data

The resource is returned as a perl data structure. Note, if there are no fields, then the http_respons is consulted, if json data is found in the content, that is returned (for instance, a plane old string or integer).

AUTHOR

David Bartle, <davidb@mediatemple.net>

COPYRIGHT & LICENSE

Copyright (c) 2014 Go Daddy Operating Company, LLC

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.