More API improvements

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": "<p><strong>My<em> canned response&nbsp;</em></strong></p>\r\n<p>%%HESK_ID%%</p>",
+ *          "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());
     }
 

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<br>`1` - Ticket opened by customer
+ * @apiSuccess {Integer} firstreplyby `0` - First reply by staff<br>`1` - First reply by customer
+ * @apiSuccess {Integer} closedby `0` - Ticket closed by staff<br>`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<br>`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<br>`false` otherwise
+ * @apiSuccess {Boolean} locked `true` if the ticket is locked<br>`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<br>`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": "<li class=\"smaller\">2014-12-28 06:57:28 | ticket created by Your name (mkoch)</li><li class=\"smaller\">2014-12-31 21:00:59 | closed by Your name (mkoch)</li><li class=\"smaller\">2014-12-31 21:01:05 | status changed to Waiting reply by Your name (mkoch)</li><li class=\"smaller\">2014-12-31 21:01:58 | closed by Your name (mkoch)</li><li class=\"smaller\">2015-01-17 16:21:18 | closed by Your name (mkoch)</li><li class=\"smaller\">2015-01-17 16:21:31 | closed by Your name (mkoch)</li><li class=\"smaller\">2015-01-17 16:22:05 | closed by Your name (mkoch)</li><li class=\"smaller\">2015-01-17 16:24:06 | status changed to  by Your name (mkoch)</li><li class=\"smaller\">2015-01-17 16:25:40 | status changed to On Hold by Your name (mkoch)</li><li class=\"smaller\">2015-01-17 16:25:53 | status changed to In Progress by Your name (mkoch)</li><li class=\"smaller\">2015-01-17 21:39:11 | locked by Your name (mkoch)</li>",
+ *           "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());
     }
 

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.
  *

api/common_api_doc.php

@@ -0,0 +1,18 @@
+<?php
+/**
+ * @apiDefine public Public
+ *      A public API can be utilized by anyone, without the use of an `X-Auth-Token`.
+ *
+ */
+/**
+ * @apiDefine protected Protected
+ *      A protected API can only be utilized by those with a valid `X-Auth-Token`.
+ */
+/**
+ * @apiDefine invalidXAuthToken 401 Unauthorized
+ *      The `X-Auth-Token` provided is invalid.
+ */
+/**
+ * @apiDefine noTokenProvided 400 Bad Request
+ *      No `X-Auth-Token` was provided.
+ */

api/dao/security_dao.php

@@ -4,7 +4,7 @@ require_once(API_PATH . 'exception/AccessException.php');
 
 function get_user_for_token_hash($hash, $hesk_settings) {
     if ($hash == NULL_OR_EMPTY_STRING) {
-        throw new AccessException(404);
+        throw new AccessException(400);
     }
 
     $user_id_sql = "SELECT `user_id` FROM `" . hesk_dbEscape($hesk_settings['db_pfix']) . "user_api_tokens`
@@ -12,7 +12,7 @@ function get_user_for_token_hash($hash, $hesk_settings) {
 
     $user_id_rs = hesk_dbQuery($user_id_sql);
     if (hesk_dbNumRows($user_id_rs) == 0) {
-        throw new AccessException(422);
+        throw new AccessException(401);
     }
     $user_id = hesk_dbFetchAssoc($user_id_rs);
 

api/exception/AccessException.php

@@ -3,7 +3,7 @@ class AccessException extends Exception {
     public function __construct($code)
     {
         $message = '';
-        if ($code == 422) {
+        if ($code == 401) {
             $message = 'The X-Auth-Token is invalid';
         }
         parent::__construct($message, $code);

api/priority/index.php

@@ -9,6 +9,10 @@ $request_method = $_SERVER['REQUEST_METHOD'];
 
 /**
  * @api {get} /priority Retrieve a ticket priority
+ * @apiVersion 0.0.0
+ * @apiName GetPriority
+ * @apiGroup Priority
+ * @apiPermission public
  *
  * @apiParam {Number} [id] The ID of the priority. Omit for all priorities.
  *

api/status/index.php

@@ -15,6 +15,10 @@ $request_method = $_SERVER['REQUEST_METHOD'];
 
 /**
  * @api {get} /status Retrieve a ticket status
+ * @apiVersion 0.0.0
+ * @apiName GetStatus
+ * @apiGroup Status
+ * @apiPermission public
  *
  * @apiParam {Number} [id] The ID of the status. Omit for all statuses.
  *