Introduction  

The JSON API that comes with TBG can be used for tasks such as retrieving issues, projects, updating issues, etc. It is also being used by the CLI tool, for all the remote tasks.

API details  

All api requests must be authenticated, or else will behave as guest authenticated. When using the CLI you can authenticate via the remote:set_server command, which will store an authentication hash locally, using the remote key listed in your account details. If you're using the remote JSON calls via your own methods, the JSON endpoints expects to have a tbg3_username and tbg3_password parameter provided. The best way to do this is using custom cookies in your request header:

$headers = "Cookie: tbg3_username={$username}; tbg3_password={$password_hash}\r\n";

where

$password_hash = crypt($password, '$2a$07$'.$salt.'$');

and

$salt = TBGSettings::getPasswordHash();

The password hash can also be retrieved as the remote authentication key from the user account overview.

Requests and responses  

Given a successful request, the response will be a json encoded string with the details listed in the endpoint description below. If the request is unsuccessful, the http response code will give you an indication of what went wrong, and there may be an error key in the json response. Example:

{error: "Incorrect project_id specified"}

Request options  

All url parameters are shown in this format:

 :parameter_name

Any parameter listed as mentioned are available in the action of the specified endpoint as:

$request['parameter_name'];
// or
$request->getParemeter('parameter_name');

Response formats  

All remote endpoints support different formatted responses. TBG comes with default json response templates for all remote endpoints, but you can make your own by adding templates with the correct response format. All endpoints therefore have a :format parameter, which by default must be "json", but can be substituted with "xml" or "html" for custom responses.

You can find which template to create by looking at the module name and action name, find the corresponding "action".json.php file and add one for your custom format. No further configuration is necessary.

Projects  

List all available projects  

CLI command	Endpoint url	Parameters	Methods	Description	Example response
remote:list_projects	/list/projects/:format	None	GET	Retrieves a list of projects. The resulting list is a list of projects formatted as project_key: project_name	/list/projects/json { "b2db": "B2DB", "caspar": "Caspar", "thebuggenie2": "The Bug Genie 2", "thebuggenie": "The Bug Genie 3" }

Issues  

CLI command	Endpoint url	Parameters	Methods	Description	Example response
-	/:project_key/issues/new	format: pass "json" as the value for the posted "format" parameter to get a json representation of the reported issue back. project_key: The project key, as specified in the response from remote:list_projects Optional arguments: This endpoint takes any available issue field as specified by remote:list_issuefields as a post parameter.	POST	Posts a new issue with the specified details, and returns the issue as a json object upon success	[[TheBugGenie:Development:JsonAPI:Examples:NewIssue
remote:list_issues	/:project_key/list/issues/:format	project_key: The project key, as specified in the response from remote:list_projects Optional arguments (default if not provided): state: "open"/"closed"(/"all") issuetype: The issue type name or key, as specified in remote:list_issuetypes assigned_to: username of assignee/"me"/"none"/("all") detailed: "yes"(/"no") See the return value when posting an issue for example of a detailed list	GET	Retrieves a list of issues for a project, based on filters	/thebuggenie/list/issues/json/state/open/assigned/me/issuetype/bugreport { "count": "181", "issues": { "1553": { "id": 1553, "title": "Double notification emails", "state": 0, "issue_no": "Bug report #895", "posted_by": "Akerbos", "assigned_to": "zegenie", "created_at": 1315336230, "status": "In progress", "last_updated": 1315936795 }, "1308": { "id": 1308, "title": "Saved searches not updating radio buttons filed as NULL then subsequently updated", "state": 0, "issue_no": "Bug report #674", "posted_by": "guest", "assigned_to": "zegenie", "created_at": 1307565979, "status": "In progress", "last_updated": 1320348067 } } }

Data  

CLI command	Endpoint url	Parameters	Methods	Description	Example response
remote:list_issuetypes	/list/issuetypes/:format	None	GET	Retrieves a list of available issue types for an issue	/list/issuetypes/json [ "Bug report", "Feature request", "Enhancement", "Task", "User story", "Documentation request" ]
remote:list_issuefields	/:project_key/list/issuefields/for/type/:issuetype/:format	project_key: The project key, as specified in the response from remote:list_projects issue_type: The issue type name or key, as specified in remote:list_issuetypes.	GET	Retrieves a list of available issue fields for the specified issue type, as configured in the issue type scheme.	/thebuggenie/list/issuefields/for/type/bugreport/json { "count": 14, "issuefields": [ "description", "reproduction_steps", "edition", "build", "component", "category", "reproducability", "resolution", "severity", "milestone", "estimated_time", "spent_time", "priority", "votes" ] }
remote:list_fieldvalues	/list/fieldvalues/for/field/:field_key/:format	field_key: The key for a field, as retrieved from remote:list_issuefields.	GET	Describes an issue field, including all available field values for that given field	/list/fieldvalues/for/field/resolution/json { "description": "Choose one of the available values", "type": "choice", "choices": { "11": "CAN'T REPRODUCE", "12": "WON'T FIX", "13": "NOT AN ISSUE", "14": "WILL FIX IN NEXT RELEASE", "15": "RESOLVED", "16": "CAN'T FIX", "40": "DUPLICATE" } }