The Bug Genie
The Bug Genie
star_faded.png
Please log in to subscribe to updates for this article
The Bug Genie:Development:Json API
Last updated at Thu Feb 04 23:53, by founderio
This page is for The Bug Genie version 3. For the new API module present in The Bug Genie version 4 (currently in development) see here: Usage

Introduction  ⇑ top

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  ⇑ top

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  ⇑ top

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  ⇑ top

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  ⇑ top

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  ⇑ top

List all available projects  ⇑ top

CLI commandEndpoint urlParametersMethodsDescriptionExample response
remote:list_projects/list/projects/:formatNoneGETRetrieves 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  ⇑ top

CLI commandEndpoint urlParametersMethodsDescriptionExample response
-/:project_key/issues/newformat: 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.
POSTPosts 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/:formatproject_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
GETRetrieves 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  ⇑ top

CLI commandEndpoint urlParametersMethodsDescriptionExample response
remote:list_issuetypes/list/issuetypes/:formatNoneGETRetrieves 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/:formatproject_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.
GETRetrieves 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/:formatfield_key: The key for a field, as retrieved from remote:list_issuefields.GETDescribes 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"
    }
}


Article attachments

There are no file attached to this article

Article comments (1)