====== Perl Client Library ======
reference implementation

This simple implementation illustrates how to use a low-level HTTP library to provide an object-oriented interface to the 4theFile API functionality. The users of the resulting module don't need to think about REST or HTTP; their interface is practically identical to what they would see if the 4theFile Resource data was stored in a local database on their server.

If you're a perl programmer, you could use this library as is, or modify it to suit your tastes. Or you might want to use the perl implementation as a model for your own development in the language of your choice.

[[http://4thefile.com/pages/static/Lib4theFileAPI.tgz | download]]

<code>
NAME
    Lib4theFileAPI - provides a simple object-oriented interface to the
    4theFile REST API as described at http://support.4thefile.com

SYNOPSIS
      use Lib4theFileAPI;
      my $api = Lib4theFileAPI->new(’https://4thefile.com/api_v1’,$username,$apiKey)
           ││ die "invalid endpoint url or credentials";
      $api->test_connect or die "failed api connection with error: ".$api->response->status_line;

      # list resources for collection ESuVkqZF that have tag "newtag"
      my $clist = $api->collection_resource_list('ESuVkqZF',{tag=>newtag}); # returns ResourceList object
  
      die "API access failed with status code ".$api->response->status_line unless $clist;

      print "public URL for 1st resource: ",$clist->resources->[0]->resource_url,"\n";

CLASS METHODS
    new(endpoint,username,apiKey);
        the endpoint should not end in /. currently all resources (except /)
        require username and password. the credentials supplied here will be
        used in future calls

        returns a new Lib4theFileAPI instance

    version()
        returns VERSION string for perl library

INSTANCE METHODS
    response()
        returns an HTTP::Response object resulting from previous API call,
        especially useful if previous call returned undef indicating a
        problem

    test_connect()
        attempts a call to the resource_list API method and returns 1 if connection was successful and valid data
        received. returns undef if connection failed (use response->status_line to see the error code returned
        from the http connection), or returns 0 if the connection was successful but no valid xml was returned by
        the server

    resource_list([$query])
        returns a Lib4theFileAPI::ResourceList object for 4theFile resources
        owned by username

        $query is an optional hashref containing query parameters as
        outlined in the API documentation. keys include page, per_page

    resource($rkey)
        returns Lib4theFileAPI::Resource object for resource key $rkey or
        undef if none found

    resource_attachment_list($rkey)
        returns a Lib4thFile::AttachmentList object containing a list of attachments (if any)
        for the top-level message in Resource, plus a little meta data (e.g. attach-
        ment_count)

    collection_resource_list($ckey,[$query])
        returns a Lib4theFileAPI::ResourceList object for 4theFile resources
        in Collection with key $ckey

        $query is an optional hashref containing query parameters as
        outlined in the API documentation. keys include page, per_page, tag, cdate

    collection($ckey)
        returns a Lib4theFileAPI::Collection object for collection with key
        $ckey or undef

    collection_list
        returns an arrayref of Lib4theFileAPI::Collection objects for
        collections owned by username

    collection_resource($ckey,$rkey)
        returns a Lib4theFileAPI::Resource object if resource $rkey exists
        and is a member of collection $ckey

    update_collection_resource($ckey,$rkey,[$query]);
        adds resource $rkey to collection $ckey if authorized (username owns
        $rkey and $ckey is public or owned by username). can also optionally
        set tags on $rkey according to the tags key in optional $query
        hashref.

        if $rkey is already in $ckey and owned by username, updates the tags

    remove_collection_resource($ckey,$rkey)
        removes resource $rkey from collection $ckey if owned by username.
        does not delete resource from 4theFile.


</code>