HappyFox API Technical Reference

Transcription

1 HappyFox API Technical Reference API Version 1.0 Document Version , Tenmiles Corporation

2 Copyright Information Under the copyright laws, this manual may not be copied, in whole or in part. Your rights to the software are governed by the HappyFox license agreement. The HappyFox logo is a trademark of Tenmiles Technologies Pvt Ltd, registered in India. Every effort has been made to ensure that the material in this manual is accurate. Other company names mentioned in this manual are trademarks of their respective companies. Mention of third-party products is for informational purposes only and constitutes neither an endorsement nor recommendation. Tenmiles Technologies Pvt. Ltd. assumes no responsibility with regard to the performance or use of these products. Tenmiles Technologies Pvt Ltd, 1A, Jhaver plaza, Nungambakkam, Chennai

3 HappyFox API - Technical Reference Table of Contents 1 Getting Started Introduction Requirements Documentation Conventions Protocols, Data Formats and Mechanisms API Version Resource URIs Base URI Request Methods Authentication Throttling Request Content Types Response Content Types Data Types NULL Values Paginated Lists for Collection Resources Parameters Paginated List - Structure Page Info - Inner Data Structure Data Validation Errors Field Errors - Structure Resources And Operations Ticket Category - Resource Operations Reading All Categories Reading One Category Data Structures Ticket Category - Structure Ticket Status - Resource Operations Reading All Statuses Reading One Status Data Structures Ticket Status - Structure Ticket Priority - Resource Operations Reading All Priorities Reading One Priority Data Structures Ticket Priority - Structure Staff - Resource Operations Reading All Staff Reading One Staff By ID Reading One Staff By Data Structures Staff - Structure User - Resource...15

4 3.5.1 Operations Reading All Users Reading One User By ID Reading One User By Data Structures User - Structure Ticket - Resource Operations Reading All Tickets Reading One Ticket Create A Ticket Add A Staff Update Add A Staff Private Note Add A User Reply Data Structures Ticket - Structure Ticket Update - Inner Data Structure Ticket Update By - Inner Data Structure Ticket Message- Inner Data Structure Ticket Attachment - Inner Data Structure Ticket Status Change - Inner Data Structure Ticket Priority Change - Inner Data Structure Ticket Assignee Change - Inner Data Structure Ticket Category Change - Inner Data Structure Ticket Due Date Change - Inner Data Structure Create Ticket - Request Data Structure Create Ticket Using User & Name - Request Data Structure Add Staff Update - Request Data Structure Add Staff Private Note - Request Data Structure Add User Reply - Request Data Structure Attachments - File Upload Request Custom Fields Operations Reading All User Custom Fields Reading One User Custom Fields Reading All Ticket Custom Fields Reading One Ticket Custom Field Types Custom Field Types Custom Field Choice Types Data Structures User Custom Field Structure Ticket Custom Field - Structure Ticket Custom Fields To Category - Inner Data Structure Choice Item - Inner Data Structure Multiple Choice Item - Inner Data Structure Custom Field Value - Inner Data Structure Notes Common Information For Setting Ticket / User Custom Field Values Ticket Custom Field Values For Create Ticket User Custom Field Values For Create Ticket...28

5 1 Getting Started 1.1 Introduction The API provided by the Helpdesk is a RESTful web service. It supports operations like creating a ticket, adding updates to a ticket, listing tickets and users of the Helpdesk, etc. It supports JSON, YAML, XML, Form Urlencoded and Multipart Form Data formats. 1.2 Requirements The API requires following skills in any programming language 1. Making HTTP requests (using and POST HTTP methods as a minimum requirement). 2. Doing HTTP Basic Authentication. 3. Generating and reading data in any one of the formats - JSON, YAML or XML 4. Optionally making HTTP POST requests using content type of "multipart/form-data" (needed for ticket attachments) 1.3 Documentation Conventions 1. The documentation indicates parameters that need to be replaced with actual values using the format <parameter_name>. The entire string including the enclosing < and > should be replaced. For example: if the parameter is < > it should be replaced with the required address

6 2 Protocols, Data Formats and Mechanisms This section of the document describes the communication protocol, data formats and application mechanisms used in the API. 2.1 API Version The resources and operations provided by the API will change over time as new features are added or existing features are modified. In order to maintain compatibility between the API clients and server each version of the API has a designated a version string. This string has to be specified as part of all the requests sent to the server. See Resource URIs for details on how to send the version number. 2.2 Resource URIs The URIs used by the API have a common base URI followed by the response data format and finally followed by the resource or collection URI. For Example, In is the Base URI <response_format>/ is a response data format like json or yaml or xml tickets/ is the Resource URI Base URI The base URI is composed of the following parts 1. HTTP or HTTPS protocol specifier 2. API server hostname 3. API server port number (optional defaults to port 80) 4. API version string 2.3 Request Methods The following HTTP methods are used to perform operations on resources provided by the API. NOTE: not all resources support all the listed operations, see the documentation of each resource for the supported methods Operation

7 POST PUT DELETE Retrieve a element or list of elements Create a new element or a child entry in a element Update a element Delete a element 2.4 Authentication The API requires a "API Key" and "Auth Code" pair for access. Contact the Helpdesk Admin for access details. The server uses HTTP Basic Authentication with the "API Key" as username and "Auth Code" as the password. The authentication realm is "API". The API server returns HTTP response code 401 in case of authorization required or login failure. SECURITY NOTES: 1. Credentials are passed as plain-text in HTTP Basic Authentication, therefore it is recommended to use SSL/TLS if the API is used over the Internet. 2. It is not recommended to invoke the API directly from browser using Javascript as this would require the "API Key" and "Auth Code" to be present on the browser side. Instead the API should be invoked from the web application server. 2.5 Throttling The API server limits the number of requests that can be sent during a interval of time. There are independent limits for read and write operations. Contact the Helpdesk Admin to know the current limits and for changing them to meet requirements. In case the request limits are exceeded the API server returns HTTP response code 503 along with the time to wait before retrying in the response body. 2.6 Request Content Types The following data formats are supported by the API server when data is sent to it for POST and PUT operations. Any of the data formats can be used provided the correct Content-Type is set in the HTTP request header. NOTE: file uploads are only supported with Multipart Form Data. Request Format Content-Type File Upload

8 JSON application/json NO YAML application/x-yaml NO Form Urlencoded application/x-www-form-urlencoded NO Multipart Form Data multipart/form-data YES 2.7 Response Content Types The following data formats are supported for response data sent back by the API server. The required data format is specified as the <response_format> mentioned under Resource URIs Response Format Specified in URI as Response Content-Type JSON json application/json YAML yaml application/x-yaml XML xml application/xml 2.8 Data Types These are the basic data types that are used in the API. Using these types more complex data structures for the resources are built. Type String Integer ID Float Boolean DateTime Date String type with Unicode support Signed 64 bit integral number Description Special type of Integer with minimum value 1, Will be unique within each resource type Floating point number True/False type Combined date and time in the ISO 8601 extended format of YYYY- MM-DD HH:MM:SS.ssssss NOTES: 1) all DateTime values in the API are in UTC timezone 2) the decimal part represented by ssssss is optional 3) a space separator is used between the date and time values Date in the ISO 8601 extended format of YYYY-MM-DD NOTE: all Date values in the API are in UTC timezone 2.9 NULL Values Some of the fields in a resource may be optional or currently absent. The values of these fields are represented as a special NULL value. This value maps to corresponding equivalents in the data formats as listed below Response Format NULL Value Representation

9 JSON YAML XML null null Element attribute null="true" 2.10 Paginated Lists for Collection Resources Some of the collection resources provided by the API may return a large volume of elements. In these cases the API imposes a upper limit on the number elements that can be returned in a single collection read request. By specifying a page size (lesser than or equal to the upper limit) and a corresponding page number as parameters, the collection can be split the into a smaller number of elements and progressively retrieved from the API server. The response from the API server contains information about the page split and the actual data as described below Parameters size Integer The number of items per page (limited to the maximum defined for the particular collection resource) page Integer The number of the page required Paginated List - Structure This data structure contains information and data from the paginated list page_info Page Info Information about the pagination data List of Elements The list of elements retrieved from the collection Page Info - Inner Data Structure This inner data structure is used in the "page_info" field of a Paginated List count Integer Number of elements returned start_index Integer The index of the first element in the returned subset end_index Integer The index of the last element in the returned subset last_index Integer The index of the last element in the entire

10 collection page_count Integer Number of pages for the given page size 2.11 Data Validation Errors The API server performs validation on the data submitted via POST and PUT requests. In case the data validation fails, the API server returns HTTP response code 400 along with error information in the response body. The error information response data is a List of Field Errors that contains information about data validation errors in individual fields as well as any errors that apply to the entire request (like errors that are not dependent on individual fields) Field Errors - Structure This data structure contains the field name and the list of errors messages for the field. field String The name of the field. (For errors that pertain to the entire request and not to a particular field, the field name will be " all ") errors List of String One or more errors related to the field value

11 3 Resources And Operations This section of the document describes the various REST element and collection resources provided by the API and the operations that can be performed on them. 3.1 Ticket Category - Resource A Ticket Category is a grouping of tickets based on a common attribute like ticket purpose, product or service, support type or department Operations Reading All Categories <base_uri>/<response_format>/categories/ List of Ticket Category Reading One Category <base_uri>/<response_format>/category/<id>/ Ticket Category Data Structures Ticket Category - Structure This data structure contains information about a ticket category id ID Unique numerical identifier name String Name of the category description String Short description about the category public Boolean If True, visible to users, else only visible to staff

12 3.2 Ticket Status - Resource A Ticket Status describes the current status of a ticket Operations Reading All Statuses <base_uri>/<response_format>/statuses/ List of Ticket Status Reading One Status <base_uri>/<response_format>/status/<id>/ Ticket Status Data Structures Ticket Status - Structure This data structure contains information about a ticket status id ID Unique numerical identifier name String Name of the status behavior String Either "pending" or "completed" to indicate the completed state of the ticket default Boolean If True, this status is the default for newly created tickets if the status is not specified

13 3.3 Ticket Priority - Resource A Ticket Priority describes the current importance of a ticket Operations Reading All Priorities <base_uri>/<response_format>/priorities/ List of Ticket Priority Reading One Priority <base_uri>/<response_format>/priority/<id>/ Ticket Priority Data Structures Ticket Priority - Structure This data structure contains information about a ticket priority id ID Unique numerical identifier name String Name of the priority default Boolean If True, this priority is the default for newly created tickets if the priority is not specified

14 3.4 Staff - Resource A Staff is a person handling Helpdesk duties like responding to incoming tickets, solving the requests / problems covered in the tickets Operations Reading All Staff Retrieve a list of all staff <base_uri>/<response_format>/staff/ List of Staff Reading One Staff By ID Retrieve details of a staff using their ID <base_uri>/<response_format>/staff/<id>/ Staff Reading One Staff By Retrieve details of a staff using the their address <base_uri>/<response_format>/staff/< >/ Staff Data Structures Staff - Structure This data structure contains information about a Helpdesk staff id ID Unique numerical identifier String address of the Staff name String Full name of the Staff

15 3.5 User - Resource A User is a person opening a ticket on the Helpdesk Operations Reading All Users Additional Params <base_uri>/<response_format>/users/? size=<size>&page=<page> Paginated List of User size: number of items per page (minimum 10, maximum 50, default 10) page: the number of the page required Reading One User By ID Retrieve details of a user using the their ID <base_uri>/<response_format>/user/<id>/ User Reading One User By Retrieve details of a user using the their address <base_uri>/<response_format>/user/< >/ User Data Structures User - Structure This data structure contains information about a user of the Helpdesk id ID Unique numerical identifier String address of the user name String Full name of the user custom_fields List of Custom Field Value The list of custom field values of the user

16 3.6 Ticket - Resource A Helpdesk request created by a User Operations Reading All Tickets Additional Params <base_uri>/<response_format>/tickets/? size=<size>&page=<page> Paginated List of Ticket size: number of items per page (minimum 10, maximum 50, default 10) page: the number of the page required Reading One Ticket <base_uri>/<response_format>/ticket/<id>/ Ticket Create A Ticket To create a ticket make a POST request to the below with request data encoded in one of the supported formats. On success it returns the newly created ticket. NOTE: file attachments are supported only when using Multipart Form Data Request Data <base_uri>/<response_format>/tickets/ POST Create Ticket or Create Ticket Using User & Name Ticket Add A Staff Update To add a staff update make a POST request to the below with request data encoded in one of the supported formats. On success it returns the modified ticket. NOTE: file attachments are supported only when using Multipart Form Data Request Data <base_uri>/<response_format>/ticket/<id>/staff_update/ POST Add Staff Update Ticket

17 Add A Staff Private Note To add a staff private note make a POST request to the below with request data encoded in one of the supported formats. On success it returns the modified ticket. Request Data <base_uri>/<response_format>/ticket/<id>/staff_pvtnote/ POST Add Staff Private Note Ticket Add A User Reply To add a user reply make a POST request to the below with request data encoded in one of the supported formats. On success it returns the modified ticket. NOTE: file attachments are supported only when using Multipart Form Data Request Data <base_uri>/<response_format>/ticket/<id>/user_reply/ POST Add User Reply Ticket Data Structures Ticket - Structure This data structure contains information about a ticket in the Helpdesk id ID Unique numerical identifier subject String The subject of the ticket category Category The category under which the ticket is present status Status The current status of the ticket priority Priority The current priority of the ticket user User The user who created the ticket assigned_to Staff The staff currently assigned created_at Timestamp The time when the ticket was created last_updated_at Timestamp The time when the ticket was last update last_accessed_at Timestamp The time when the ticket was last accessed last_user_reply_at Timestamp The time when a user last replied to a ticket last_staff_reply_at Timestamp The time when a staff last replied to a ticket time_spent Integer Total time spent by staff on the ticket

18 due_date Date The due date for completion of the ticket updates custom_fields List of Ticket Update List of Custom Field Value Ticket Update - Inner Data Structure The list of updates that were done on a ticket The list of custom fields values in the ticket This is a inner data structure present in the "updates" field of Ticket. It is used to describe the updates done on the ticket. timestamp DateTime The time when the update was added by message status_change priority_change assignee_change category_change due_date_change time_spent Ticket Update By Ticket Message Ticket Status Change Ticket Priority Change Ticket Assignee Change Ticket Category Change Ticket Due Date Change Integer By who was the ticket updated Details of the message The IDs of the old and new Statuses The IDs of the old and new Priorities The IDs of the old and new Staff The IDs of the old and new categories The the old and new due dates Time spent by staff on the ticket Ticket Update By - Inner Data Structure This is a inner data structure present in the "by" field of Ticket Update. It is used to describe the source of the update. type String "staff" or "user" or "smartrule" to indicate the who updated the ticket id ID ID of the corresponding staff/user/smartrule

19 Ticket Message- Inner Data Structure This is a inner data structure present in the "message" field of Ticket Update. It is used to describe the message update on a ticket. subject String The subject of the message text String The message text in plain-text format html String The message text in HTML format attachments List of Ticket Attachment The file attachments for this message message_type String p - Private Note f - Forward null staff/customer update cc_list String Comma separated list of addresses bcc_list String Comma separated list of addresses forward_list String Comma separated list of addresses to which the ticket is forwarded and it's present only for forwarded messages i.e. message_type = f Ticket Attachment - Inner Data Structure This is a inner data structure present in the "attachments" field of Ticket Message. It is used to describe the file attachments for a message. filename String The name of the file url String The where the attachment can be accessed Ticket Status Change - Inner Data Structure This is a inner data structure present in the "status_change" field of Ticket Update. It is used to describe the status change of a ticket. old ID ID of the old status new ID ID of the new status Ticket Priority Change - Inner Data Structure This is a inner data structure present in the "priority_change" field of Ticket Update. It is used to describe the priority change of a ticket.

20 old ID ID of the old priority new ID ID of the new priority Ticket Assignee Change - Inner Data Structure This is a inner data structure present in the "assignee_change" field of Ticket Update. It is used to describe the change of a ticket's assigned staff. old new ID ID ID of the old staff ID of the new staff Ticket Category Change - Inner Data Structure This is a inner data structure present in the "category_change" field of Ticket Update. It is used to describe the category change of a ticket. old ID ID of the old category new ID ID of the new category Ticket Due Date Change - Inner Data Structure This is a inner data structure present in the "due_date_change" field of Ticket Update. It is used to describe the change of a ticket due date. old Date Old due date new Date New due date Create Ticket - Request Data Structure This data structure contains information required to create a ticket. NOTE: Any custom fields required for the ticket need to be appended to the list below. See Ticket Custom Field Values For Create Ticket for information. subject String The ticket subject text String The ticket message in plain-text format attachments Attachments The file attachments for this ticket

21 category ID ID of the ticket category priority ID ID of the ticket priority user ID ID of the user creating the ticket Create Ticket Using User & Name - Request Data Structure This data structure contains information required to create a ticket. This variation uses the and name of a user. If the already exists in the Helpdesk, the corresponding user is used, else a new user is created. NOTE: Any custom fields required for the ticket and user need to be appended to the list below. See Ticket Custom Field Values For Create Ticket and User Custom Field Values For Create Ticket for information. subject String The ticket subject text String The ticket message in plain-text format attachments Attachments The file attachments for this ticket category ID ID of the ticket category priority ID ID of the ticket priority String address of the user name String Full name of the user Add Staff Update - Request Data Structure This data structure contains information required to add an staff update to a ticket. staff ID ID of the staff adding this update subject String The update subject text String The update message in plain-text format cc String Comma separated list of addresses bcc String Comma separated list of addresses attachments Attachments The file attachments for this update status priority assignee ID ID ID ID of the ticket's new status ID of the ticket's new priority ID of staff the ticket is reassigned to time_spent Integer Time spent by the staff on this ticket

22 due_date tags Date String New due date for the ticket Comma separated list of tags notify_user Boolean If True, send notification to the user about this update Add Staff Private Note - Request Data Structure This data structure contains information required to add an staff private note to a ticket. staff ID ID of the staff adding this update subject String New subject for the ticket text String The update message in plain-text format status priority time_spent due_date tags alert_to ID ID Integer Date String ID ID of the ticket's new status ID of the ticket's new priority Time spent by the staff on this ticket New due date for the ticket New tags as comma separated list Add User Reply - Request Data Structure ID of a staff to send notification to (cannot be the same as the ID used for the staff field) This data structure contains information required to add an user reply to a ticket. user ID ID of the user sending this reply text String The reply message in plain-text format cc String Comma separated list of addresses bcc String Comma separated list of addresses attachments Attachments The file attachments for this reply Attachments - File Upload Request This section describes the request format to be used for upload file attachments for

23 creating a ticket or in a reply/update. File uploads are only supported with Multipart Form Data format. To upload a file, construct the request as documented at (check if library functions are available in your programming languages to prepare Multipart Form Data requests) To upload multiple files, repeat the "attachments" field as required.

24 3.7 Custom Fields Custom fields allow additional data to be added to the Helpdesk as required. Custom fields can be defined for independently for users and tickets. For example, a phone number custom field can be added for users Operations Reading All User Custom Fields <base_uri>/<response_format>/user_custom_fields/ List of User Custom Field Reading One User Custom Fields <base_uri>/<response_format>/user_custom_field/<id>/ User Custom Field Reading All Ticket Custom Fields <base_uri>/<response_format>/ticket_custom_fields/ List of Ticket Custom Field Reading One Ticket Custom Field <base_uri>/<response_format>/ticket_custom_field/<id>/ Ticket Custom Field Types Custom Field Types Custom fields can be of the following data types Custom Field Type text number choice multiple_choice Data Type Of Value String Float String List of String

25 Custom Field Choice Types A custom field's choice can be of the following types based on the type of the custom field Custom Field Type text number choice multiple_choice Value for Choices NULL NULL List of Choice Item List of Multiple Choice Item Data Structures User Custom Field Structure This data structure contains information about a custom field defined for users id ID Unique numerical identifier name String Name of the custom field type String A type as listed in Custom Field Types depends_on_choice ID ID of the choice that this custom field depends on required Boolean If true, this field has to be filled in when creating a new ticket visible_to_staff_only Boolean If true, this field is private to staff alone and should not be shown to the users choices Depends on type as listed in Custom Field Choice Types Choices for "choice" and "multiple_choice" custom fields, NULL for other types order Integer The order in which to show custom fields during data entry or display Ticket Custom Field - Structure This data structure contains information about a custom field defined for tickets. Each ticket category can have its own sub-set of ticket custom fields, this information is contained in the "categories" field of the data structure. id ID Unique numerical identifier name String Name of the custom field type Custom Field Type A type as listed in Custom Field Types depends_on_choice ID ID of the choice that this custom field

26 depends on required Boolean If true, this field has to be filled in when creating a new ticket visible_to_staff_only Boolean If true, this field is private to staff alone and should not be shown to the users choices Depends on type as listed in Custom Field Choice Types The choices for "choice" and "multiple_choice" custom fields, NULL for other types compulsory_on_completed Boolean If true, this field has to be filled in before the ticket can be set to any of the completed Status categories List of Ticket Custom Fields To Category Information about which categories this custom field is present in and the display order Ticket Custom Fields To Category - Inner Data Structure This is a inner data structure present in the "categories" field of Ticket Custom Field. It is used to define which ticket categories the ticket custom field is associated with. category ID ID of the category in which the Ticket Custom Field appears order Integer The order in which to show custom fields during data entry or display Choice Item - Inner Data Structure This is a inner data structure present in the "choices" field of User Custom Field and Ticket Custom Field. It is used to define which choices are defined in this "choice" type custom field. id ID Unique numerical identifier text String The text of the choice dependant_fields List of ID IDs of the custom fields that depend on this choice Multiple Choice Item - Inner Data Structure This is a inner data structure used for the "choices" field of User Custom Field and Ticket Custom Field. It is used to define which choices are defined in this "multiple_choice" type custom field.

27 id ID Unique numerical identifier text String The text of the choice Custom Field Value - Inner Data Structure This is a inner data structure used for the "custom_fields" field of User and Ticket. It is used to define the value of the custom field. name String Name of the custom field type String A type as listed in Custom Field Types value Notes Depends on type as listed in Custom Field Types Value of the custom field Common Information For Setting Ticket / User Custom Field Values 1. When the "depends_on_choice" field of a custom field set to a non-null value, it is applicable only when the corresponding choice is selected. The "dependant_fields" field of Choice Item can also be used to determine which custom fields are applicable when the choice is selected 2. Values for "multiple_choice" type custom fields should be sent as multiple fields with the same field name when using Form Urlencoded and Multipart Form Data formats. The values can be sent as List for JSON and YAML formats Ticket Custom Field Values For Create Ticket 1. All the points in Common Information For Setting Ticket / User Custom Field Values 2. The values for ticket custom fields should be appended to the fields for Create Ticket 3. The value for a ticket custom field should be sent using a field name constructed from the ID of the ticket custom field in the following format "t-cf-<id>" 4. The ticket custom fields applicable to a ticket are dependent on the ticket's category. This can be determined from the "categories" field of Ticket Custom Field

28 User Custom Field Values For Create Ticket 1. All the points in Common Information For Setting Ticket / User Custom Field Values 2. The values for user custom fields should be appended to the fields for Create Ticket 3. The value for a user custom fields should be sent using a field name constructed from the ID of the user custom field in the following format "c-cf-<id>"