From eb6261624781b1cca15edd1f55a8d4b1c5b120f8 Mon Sep 17 00:00:00 2001 From: Mike Koch Date: Sat, 28 Nov 2015 22:25:51 -0500 Subject: [PATCH] More API improvements --- api/admin/canned/index.php | 30 +++++++- api/admin/ticket/index.php | 117 +++++++++++++++++++++++++++++- api/category/index.php | 4 +- api/common_api_doc.php | 18 +++++ api/dao/security_dao.php | 4 +- api/exception/AccessException.php | 2 +- api/priority/index.php | 6 +- api/status/index.php | 6 +- 8 files changed, 174 insertions(+), 13 deletions(-) create mode 100644 api/common_api_doc.php diff --git a/api/admin/canned/index.php b/api/admin/canned/index.php index 47c95fc6..bd4357c4 100644 --- a/api/admin/canned/index.php +++ b/api/admin/canned/index.php @@ -14,15 +14,39 @@ hesk_dbConnect(); // Routing $request_method = $_SERVER['REQUEST_METHOD']; + +/** + * @api {get} /admin/canned Retrieve a canned response + * @apiVersion 0.0.0 + * @apiName GetCanned + * @apiGroup Canned Response + * @apiPermission protected + * + * @apiParam {Number} [id] The ID of the canned response. Omit for all canned responses. + * + * @apiSuccess {Number} id ID of the canned response + * @apiSuccess {String} title The title of the canned response. + * @apiSuccess {String} message The contents of the canned response, including HTML markup. + * @apiSuccess {Integer} reply_order The position of the canned response in the list of canned responses (in multiples of 10). + * + * @apiSuccessExample {json} Success-Response: + * HTTP/1.1 200 OK + * { + * "id": 2, + * "title": "html", + * "message": "

My canned response 

\r\n

%%HESK_ID%%

", + * "reply_order": 10 + * } + * + * @apiError (noTokenProvided) 400 No `X-Auth-Token` was provided where it is required + * @apiError (invalidXAuthToken) 401 The `X-Auth-Token` provided was invalid + */ if ($request_method == 'GET') { $token = get_header('X-Auth-Token'); try { get_user_for_token($token, $hesk_settings); } catch (AccessException $e) { - if ($e->getCode() == 422) { - print_error($e->getMessage(), $e->getMessage()); - } return http_response_code($e->getCode()); } diff --git a/api/admin/ticket/index.php b/api/admin/ticket/index.php index 033cede5..521a1118 100644 --- a/api/admin/ticket/index.php +++ b/api/admin/ticket/index.php @@ -14,15 +14,126 @@ hesk_dbConnect(); // Routing $request_method = $_SERVER['REQUEST_METHOD']; + +/** + * @api {get} /admin/ticket Retrieve a ticket (staff-side) + * @apiVersion 0.0.0 + * @apiName GetTicketStaff + * @apiGroup Ticket + * @apiPermission protected + * + * @apiParam {Number} [id] The ID of the ticket. Omit for all tickets. + * + * @apiSuccess {Number} id ID of the ticket + * @apiSuccess {String} trackid The tracking id of the ticket + * @apiSuccess {String} name The name of the contact + * @apiSuccess {String} email The email address of the ticket (empty string if no email) + * @apiSuccess {Integer} category The ID of the category the ticket is in + * @apiSuccess {Integer} priority The ID of the priority the ticket is in + * @apiSuccess {String} subject The subject of the ticket + * @apiSuccess {String} message The original message of the ticket + * @apiSuccess {String} dt The date and time the ticket was submitted, in `YYYY-MM-DD hh:mm:ss` + * @apiSuccess {String} lastchange The date and time the ticket was last changed, in `YYYY-MM-DD hh:mm:ss` + * @apiSuccess {String} firstreply The date and time the first remply was recorded, in `YYYY-MM-DD hh:mm:ss` + * @apiSuccess {String} closedat The date and time the ticket was closed, in `YYYY-MM-DD hh:mm:ss` + * @apiSuccess {Integer} articles The knowledgebase article IDs suggested when the user created the ticket + * @apiSuccess {String} ip The IP address of the submitter + * @apiSuccess {String} language The language the ticket was submitted in + * @apiSuccess {Integer} status The ID of the status the ticket is set to + * @apiSuccess {Integer} openedby `0` - Ticket opened by staff
`1` - Ticket opened by customer + * @apiSuccess {Integer} firstreplyby `0` - First reply by staff
`1` - First reply by customer + * @apiSuccess {Integer} closedby `0` - Ticket closed by staff
`1` - Ticket closed by customer + * @apiSuccess {Integer} replies Total number of replies to ticket + * @apiSuccess {Integer} staffreplies Total number of replies to ticket from staff + * @apiSuccess {Integer} owner The user ID of the ticket owner + * @apiSuccess {String} time_worked The total time worked on the ticket, in `hh:mm:ss` + * @apiSuccess {Integer} lastreplier `0` - Last reply by staff
`1` - Last reply by customer + * @apiSuccess {Integer} replierid The user ID of the staff that last replied to the ticket, or `0` if the last reply was made by the customer + * @apiSuccess {Boolean} archive `true` if the ticket is tagged
`false` otherwise + * @apiSuccess {Boolean} locked `true` if the ticket is locked
`false` otherwise + * @apiSuccess {Binary[]} attachments Array of attachments, in base-64 encoded binary + * @apiSuccess {Integer[]} merged Array of merged ticket IDs + * @apiSuccess {String} history HTML markup of the entire "Audit Trail" section + * @apiSuccess {String} custom1-20 Custom fields 1-20's values. + * @apiSuccess {Integer} parent The ID of the ticket linked to this ticket + * @apiSuccess {String} latitude The latitudinal coordinate of the user's location, or one of the corresponding error codes. + * @apiSuccess {String} longitude The longitudinal coordinate of the user's location, or one of the corresponding error codes. + * @apiSuccess {Boolean} html `true` if the ticket was created with HTML encoding
`false` otherwise + * @apiSuccess {String} user_agent The user agent of the user who submitted the ticket + * @apiSuccess {Integer} screen_resolution_width The width of the screen resolution of the user who submitted the ticket + * @apiSuccess {Integer} screen_resolution_height The height of the screen resolution of the user who submitted the ticket + * + * @apiSuccessExample {json} Success-Response: + * HTTP/1.1 200 OK + * { + * "id": 22, + * "trackid": "EVL-RRL-DUBG", + * "name": "Test", + * "email": "", + * "category": 1, + * "priority": 3, + * "subject": "test", + * "message": "test", + * "dt": "2014-12-28 00:57:26", + * "lastchange": "2015-03-08 23:38:59", + * "firstreply": "2015-01-17 10:21:16", + * "closedat": "2015-01-17 15:39:12", + * "articles": null, + * "ip": "::1", + * "language": null, + * "status": 3, + * "openedby": 0, + * "firstreplyby": "1", + * "closedby": "1", + * "replies": "11", + * "staffreplies": "10", + * "owner": "1", + * "time_worked": "00:05:07", + * "lastreplier": 1, + * "replierid": 1, + * "archive": true, + * "locked": true, + * "attachments": "", + * "merged": "", + * "history": "
  • 2014-12-28 06:57:28 | ticket created by Your name (mkoch)
  • 2014-12-31 21:00:59 | closed by Your name (mkoch)
  • 2014-12-31 21:01:05 | status changed to Waiting reply by Your name (mkoch)
  • 2014-12-31 21:01:58 | closed by Your name (mkoch)
  • 2015-01-17 16:21:18 | closed by Your name (mkoch)
  • 2015-01-17 16:21:31 | closed by Your name (mkoch)
  • 2015-01-17 16:22:05 | closed by Your name (mkoch)
  • 2015-01-17 16:24:06 | status changed to by Your name (mkoch)
  • 2015-01-17 16:25:40 | status changed to On Hold by Your name (mkoch)
  • 2015-01-17 16:25:53 | status changed to In Progress by Your name (mkoch)
  • 2015-01-17 21:39:11 | locked by Your name (mkoch)
    • ", + * "custom1": "1420671600", + * "custom2": "", + * "custom3": "", + * "custom4": "", + * "custom5": "", + * "custom6": "", + * "custom7": "", + * "custom8": "", + * "custom9": "", + * "custom10": "", + * "custom11": "", + * "custom12": "", + * "custom13": "", + * "custom14": "", + * "custom15": "", + * "custom16": "", + * "custom17": "", + * "custom18": "", + * "custom19": "", + * "custom20": "", + * "parent": null, + * "latitude": "E-0", + * "longitude": "E-0", + * "html": false, + * "user_agent": null, + * "screen_resolution_width": null, + * "screen_resolution_height": null + * } + * + * @apiError (noTokenProvided) 400 No `X-Auth-Token` was provided where it is required + * @apiError (invalidXAuthToken) 401 The `X-Auth-Token` provided was invalid + */ if ($request_method == 'GET') { $token = get_header('X-Auth-Token'); try { get_user_for_token($token, $hesk_settings); } catch (AccessException $e) { - if ($e->getCode() == 422) { - print_error($e->getMessage(), $e->getMessage()); - } return http_response_code($e->getCode()); } diff --git a/api/category/index.php b/api/category/index.php index 1f216313..df068488 100644 --- a/api/category/index.php +++ b/api/category/index.php @@ -18,7 +18,7 @@ $request_method = $_SERVER['REQUEST_METHOD']; * @apiVersion 0.0.0 * @apiName GetCategory * @apiGroup Category - * @apiPermission none + * @apiPermission public * * @apiParam {Number} [id] The ID of the category. Omit for all categories. * @@ -40,7 +40,7 @@ $request_method = $_SERVER['REQUEST_METHOD']; * "type": 0, * "priority": 2, * "manager": 0 - * } + * } */ if ($request_method == 'GET') { if (isset($_GET['id'])) { diff --git a/api/common_api_doc.php b/api/common_api_doc.php new file mode 100644 index 00000000..6212e53a --- /dev/null +++ b/api/common_api_doc.php @@ -0,0 +1,18 @@ +