perl_client_library
Differences
This shows you the differences between two versions of the page.
|
perl_client_library [2010/11/05 18:20] jay |
perl_client_library [2011/11/10 19:34] (current) jay |
||
|---|---|---|---|
| Line 4: | Line 4: | ||
| 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. | 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 this perl implementation as a model for your own development in the language of your choice. | + | 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. |
| - | documentation and download link coming soon! | + | [[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> | ||
perl_client_library.1288981206.txt.gz · Last modified: 2010/11/05 18:20 by jay