Using builder pattern & fluid interface

[aik099]

Currently, all of the public methods (direct calls to the Api::api method outside of the library or internal calls to the Api::api method from inside the library) follow this pattern in preparation of the upcoming API call:

1. (URL part) build an URL from method parameters (e.g. sprintf('/rest/api/2/issue/%s/worklog', $issue_key)) or hardcode it inside the method (e.g. '/rest/api/2/issuetype')
2. (Request body part) either specify method parameters as-is to the performed API call (e.g. Api::getIssue method) or transform them as needed (e.g. Api::addWorklog)
3. (only for GET requests currently; Query parameters part) specify what should be appended to the URL
4. specify if this a file-uploading request
5. specify if the request needs to be debugged

Proposing these changes:

Before:

// Before:
$api->deleteWorklog('JRE-123', 124353, array('custom' => 'param'));
$api->addWorklog('JRE-123', '12m', array('comment' => 'test', '_query' => array('notifyUsers' => false));

// After:
$api->withRequestBody(array('custom' => 'param'))->deleteWorklog('JRE-123', 124353);
$api->withRequestBody(array('comment' => 'test'))->withQueryParameters(array('notifyUsers' => false))->addWorklog('JRE-123', '12m');

The file support could be added using withFile(...) method.

This way the with... methods will just collect the data and supply it to the Api::api method. The API method itself will consume these parameters and clear previously stored ones to avoid them being passed to the next API call made.

The proposed approach greatly reduces boilerplate code for new API call method creation and adds built-in support for Request body and Query parameters support for every API call.

P.S. The mentioned _query key of the $params array will be supported only after #222 merge.

// cc: @jpastoor , @glensc

[aik099]

On one hand, I want to give flexibility to developers in specifying whatever parameters they need (it could be a combination of Request body and Query parameters). On the other hand, I want to be simple. The proposed change won't make it simpler IMO, but would add more features.

What I'm trying to avoid is to have $params array where user can't control what key goes to Request body and what key goes to Query parameters. If we can solve this problem by other means I'm open to suggestions.