SYNOPSIS

        use API::Basecamp;
    
        my $basecamp = API::Basecamp->new(
            username   => 'USERNAME',
            password   => 'PASSWORD',
            identifier => 'APPLICATION (yourname@example.com)',
            account    => '999999999',
        );
    
        my $project = $basecamp->projects(12345);
        my $results = $project->fetch;
    
        # after some introspection
    
        $project->delete;

DESCRIPTION

    This distribution provides an object-oriented thin-client library for
    interacting with the Basecamp (http://basecamp.com) API. For usage and
    documentation information visit https://github.com/basecamp/bcx-api.

THIN CLIENT

    A thin-client library is advantageous as it has complete coverage and
    can easily adapt to changes in the API with minimal effort. As a
    thin-client library, this module does not map specific HTTP requests to
    specific routines nor does it provide parameter validation, pagination,
    or other conventions found in typical API client implementations,
    instead, it simply provides a simple and consistent mechanism for
    dynamically generating HTTP requests. Additionally, this module has
    support for debugging and retrying API calls as well as throwing
    exceptions when 4xx and 5xx server response codes are received.

 Building

        my $project = $basecamp->projects(12345);
        my $todolists = $project->todolists;
    
        $todolists->action; # GET /projects/12345/todolists
        $todolists->action('head'); # HEAD /projects/12345/todolists

    Building up an HTTP request object is extremely easy, simply call
    method names which correspond to the API's path segments in the
    resource you wish to execute a request against. This module uses
    autoloading and returns a new instance with each method call. The
    following is the equivalent:

        my $project = $basecamp->resource(projects => 12345);
        my $todolists = $project->resource('todolists');
    
        # or
    
        my $todolists = $basecamp->resource('projects', 12345, 'todolists');
    
        # then
    
        $todolists->action('put', %args); # PUT /projects/12345/todolists

    Because each call returns a new API instance configured with a resource
    locator based on the supplied parameters, reuse and request isolation
    are made simple, i.e., you will only need to configure the client once
    in your application.

 Fetching

        my $projects = $basecamp->projects;
    
        $projects->fetch(
            query => {
                # query-string parameters
            },
        );
    
        # equivalent to
    
        $basecamp->resource('projects')->action(
            get => ( query => { ... } )
        );

    This example illustrates how you might fetch an API resource.

 Creating

        my $projects = $basecamp->projects;
    
        $projects->create(
            data => {
                # content-body parameters
            },
            query => {
                # query-string parameters
            },
        );
    
        # or
    
        my $projects = $basecamp->projects->create(...);
    
        # equivalent to
    
        $basecamp->resource('projects')->action(
            post => ( query => { ... }, data => { ... } )
        );

    This example illustrates how you might create a new API resource.

 Updating

        my $projects = $basecamp->projects;
        my $project  = $projects->resource(12345);
    
        $project->update(
            data => {
                # content-body parameters
            },
            query => {
                # query-string parameters
            },
        );
    
        # or
    
        my $project = $basecamp->projects(12345);
    
        $project->update(...);
    
        # equivalent to
    
        $basecamp->resource('projects')->action(
            put => ( query => { ... }, data => { ... } )
        );

    This example illustrates how you might update an new API resource.

 Deleting

        my $projects = $basecamp->projects;
        my $project  = $projects->resource(12345);
    
        $project->delete(
            data => {
                # content-body parameters
            },
            query => {
                # query-string parameters
            },
        );
    
        # or
    
        my $project = $basecamp->projects(12345);
    
        $project->delete(...);
    
        # equivalent to
    
        $basecamp->resource('projects')->action(
            delete => ( query => { ... }, data => { ... } )
        );

    This example illustrates how you might delete an API resource.

 Transacting

        my $project = $basecamp->resource('projects', '12345');
    
        my ($results, $transaction) = $project->fetch(...);

    This example illustrates how you can access the transaction object used
    to submit the HTTP request.

        $basecamp->username;
        $basecamp->username('USERNAME');

    The username parameter should be set to the account holder's username.

        $basecamp->password;
        $basecamp->password('PASSWORD');

    The password parameter should be set to the account holder's password.

        $basecamp->identifier;
        $basecamp->identifier('IDENTIFIER');

    The identifier parameter should be set using a string to identify your
    app.

        $basecamp->account;
        $basecamp->account('ACCOUNT');

    The account parameter should be set to the account holder's account ID
    number.

        $basecamp->debug;
        $basecamp->debug(1);

    The debug attribute if true prints HTTP requests and responses to
    standard out.

        $basecamp->fatal;
        $basecamp->fatal(1);

    The fatal attribute if true promotes 4xx and 5xx server response codes
    to exceptions, a API::Basecamp::Exception object.

        $basecamp->retries;
        $basecamp->retries(10);

    The retries attribute determines how many times an HTTP request should
    be retried if a 4xx or 5xx response is received. This attribute
    defaults to 0.

        $basecamp->timeout;
        $basecamp->timeout(5);

    The timeout attribute determines how long an HTTP connection should be
    kept alive. This attribute defaults to 10.

        $basecamp->url;
        $basecamp->url(Mojo::URL->new('https://basecamp.com'));

    The url attribute set the base/pre-configured URL object that will be
    used in all HTTP requests. This attribute expects a Mojo::URL object.

        $basecamp->user_agent;
        $basecamp->user_agent(Mojo::UserAgent->new);

    The user_agent attribute set the pre-configured UserAgent object that
    will be used in all HTTP requests. This attribute expects a
    Mojo::UserAgent object.

        my $result = $basecamp->action($verb, %args);
    
        # e.g.
    
        $basecamp->action('head', %args);   # HEAD request
        $basecamp->action('optons', %args); # OPTIONS request
        $basecamp->action('patch', %args);  # PATCH request

    The action method issues a request to the API resource represented by
    the object. The first parameter will be used as the HTTP request
    method. The arguments, expected to be a list of key/value pairs, will
    be included in the request if the key is either data or query.

        my $results = $basecamp->create(%args);
    
        # or
    
        $basecamp->POST(%args);

    The create method issues a POST request to the API resource represented
    by the object. The arguments, expected to be a list of key/value pairs,
    will be included in the request if the key is either data or query.

        my $results = $basecamp->delete(%args);
    
        # or
    
        $basecamp->DELETE(%args);

    The delete method issues a DELETE request to the API resource
    represented by the object. The arguments, expected to be a list of
    key/value pairs, will be included in the request if the key is either
    data or query.

        my $results = $basecamp->fetch(%args);
    
        # or
    
        $basecamp->GET(%args);

    The fetch method issues a GET request to the API resource represented
    by the object. The arguments, expected to be a list of key/value pairs,
    will be included in the request if the key is either data or query.

        my $results = $basecamp->update(%args);
    
        # or
    
        $basecamp->PUT(%args);

    The update method issues a PUT request to the API resource represented
    by the object. The arguments, expected to be a list of key/value pairs,
    will be included in the request if the key is either data or query.

        $basecamp->accesses;

    The accesses method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/accesses.md.

        $basecamp->attachments;

    The attachments method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/attachments.md
    .

        $basecamp->authentication;

    The authentication method returns a new instance representative of the
    API resource requested. This method accepts a list of path segments
    which will be used in the HTTP request. The following documentation can
    be used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/authentication
    .md.

        $basecamp->calendar_events;

    The calendar_events method returns a new instance representative of the
    API resource requested. This method accepts a list of path segments
    which will be used in the HTTP request. The following documentation can
    be used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/calendar_event
    s.md.

        $basecamp->calendars;

    The calendars method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/calendars.md.

        $basecamp->comments;

    The comments method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/comments.md.

        $basecamp->documents;

    The documents method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/documents.md.

        $basecamp->events;

    The events method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/events.md.

        $basecamp->forwards;

    The forwards method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/forwards.md.

        $basecamp->groups;

    The groups method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/groups.md.

        $basecamp->messages;

    The messages method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/messages.md.

        $basecamp->people;

    The people method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/people.md.

        $basecamp->project_templates;

    The project_templates method returns a new instance representative of
    the API resource requested. This method accepts a list of path segments
    which will be used in the HTTP request. The following documentation can
    be used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/project_templa
    tes.md.

        $basecamp->projects;

    The projects method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/projects.md.

        $basecamp->stars;

    The stars method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/stars.md.

        $basecamp->tags;

    The tags method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/tags.md.

        $basecamp->todolists;

    The todolists method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/todolists.md.

        $basecamp->todos;

    The todos method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/todos.md.

        $basecamp->topics;

    The topics method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/topics.md.

        $basecamp->uploads;

    The uploads method returns a new instance representative of the API
    resource requested. This method accepts a list of path segments which
    will be used in the HTTP request. The following documentation can be
    used to find more information.
    https://github.com/basecamp/bcx-api/blob/master/sections/uploads.md.

POD ERRORS

    Hey! The above document had some coding errors, which are explained
    below:

    Around line 175:

      Unknown directive: =param

    Around line 182:

      Unknown directive: =param

    Around line 189:

      Unknown directive: =param

    Around line 196:

      Unknown directive: =param

    Around line 203:

      Unknown directive: =attr

    Around line 210:

      Unknown directive: =attr

    Around line 218:

      Unknown directive: =attr

    Around line 226:

      Unknown directive: =attr

    Around line 234:

      Unknown directive: =attr

    Around line 242:

      Unknown directive: =attr

    Around line 250:

      Unknown directive: =method

    Around line 266:

      Unknown directive: =method

    Around line 278:

      Unknown directive: =method

    Around line 290:

      Unknown directive: =method

    Around line 302:

      Unknown directive: =method

    Around line 314:

      Unknown directive: =resource

    Around line 323:

      Unknown directive: =resource

    Around line 332:

      Unknown directive: =resource

    Around line 341:

      Unknown directive: =resource

    Around line 350:

      Unknown directive: =resource

    Around line 359:

      Unknown directive: =resource

    Around line 368:

      Unknown directive: =resource

    Around line 377:

      Unknown directive: =resource

    Around line 386:

      Unknown directive: =resource

    Around line 395:

      Unknown directive: =resource

    Around line 404:

      Unknown directive: =resource

    Around line 413:

      Unknown directive: =resource

    Around line 422:

      Unknown directive: =resource

    Around line 431:

      Unknown directive: =resource

    Around line 440:

      Unknown directive: =resource

    Around line 449:

      Unknown directive: =resource

    Around line 458:

      Unknown directive: =resource

    Around line 467:

      Unknown directive: =resource

    Around line 476:

      Unknown directive: =resource

    Around line 485:

      Unknown directive: =resource