From 55a8cc2673d57276cb86366a45f2f545fe70278d Mon Sep 17 00:00:00 2001
From: Jared Hancock <jared@osticket.com>
Date: Fri, 16 Nov 2012 15:48:38 -0600
Subject: [PATCH] Add more polish to the API docs
---
setup/doc/api.md | 5 +++
setup/doc/api/tickets.md | 96 +++++++++++++++++++++++-----------------
2 files changed, 60 insertions(+), 41 deletions(-)
diff --git a/setup/doc/api.md b/setup/doc/api.md
index 9f13dab82..7509616aa 100644
--- a/setup/doc/api.md
+++ b/setup/doc/api.md
@@ -12,6 +12,11 @@ Authentication via the API is done via API keys configured inside the
osTicket admin panel. API keys are created and tied to a source IP address,
which will be checked against the source IP of requests to the HTTP API.
+API keys can be created and managed via the admin panel. Navigate to Manage
+-> API keys. Use *Add New API Key* to create a new API key. Currently, no
+special configuration is required to allow the API key to be used for the
+HTTP API. All API keys are valid for the HTTP API.
+
Wrappers
--------
diff --git a/setup/doc/api/tickets.md b/setup/doc/api/tickets.md
index df74b0926..fc79b1aea 100644
--- a/setup/doc/api/tickets.md
+++ b/setup/doc/api/tickets.md
@@ -8,25 +8,24 @@ now.
Create a Ticket
---------------
+Tickets can be created in the osTicket system by sending an HTTP POST to
+`api/tickets.xml` or `api/tickets.json` depending on the format of the
+request content.
+
### Fields ######
* __email__: *required* Email address of the submitter
* __name__: *required* Name of the submitter
* __subject__: *required* Subject of the ticket
* __message__: *required* Initial message for the ticket thread
-
* __alert__: If unset, disable alerts to staff. Default is `true`
-* __autorespond__: If unset, disable autoresponses. Default is
- `true`
+* __autorespond__: If unset, disable autoresponses. Default is `true`
* __ip__: IP address of the submitter
-* __phone__: Phone number of the submitter. See examples below for
- embedding the extension with the phone number
-* __phone_ext__: Phone number extension -- can also be embedded in
- *phone*
+* __phone__: Phone number of the submitter
+* __phone_ext__: Phone number extension -- can also be embedded in *phone*
* __priorityId__: Priority *id* for the new ticket to assume
* __source__: Source of the ticket, default is `API`
* __topicId__: Help topic *id* associated with the ticket
-
* __attachments__: An array of files to attach to the initial message.
Each attachment must have some content and also the
following fields:
@@ -35,7 +34,9 @@ Create a Ticket
* __type__: Mime type of the file. Default is `text/plain`
* __encoding__: Set to `base64` if content is base64 encoded
-### XMl Payload Example ######
+### XML Payload Example ######
+
+* `POST /api/tickets.xml`
The XML data format is extremely lax. Content can be either sent as an
attribute or a named element if it has no sub-content.
@@ -48,25 +49,36 @@ quotes is to be embedded, simple sub-elements are also supported.
Notice that the phone extension can be sent as the `@ext` attribute of the
`phone` sub-element.
- <?xml version="1.0" encoding="UTF-8"?>
- <ticket alert="true" autorespond="true" source="API">
- <name>Peter Rotich</name>
- <email>peter@osticket.com</email>
- <subject>Testing API</subject>
- <phone ext="123">504-305-8634</phone>
- <message><![CDATA[Message content here]]></message>
- <attachments>
- <file name="file.txt" type="plain/text"
- encoding="base64"><![CDATA[
- File content is here and is automatically trimmed
- ]]></file>
- </attachments>
- <ip>123.211.233.122</ip>
- </ticket>
+``` xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ticket alert="true" autorespond="true" source="API">
+ <name>Angry User</name>
+ <email>api@osticket.com</email>
+ <subject>Testing API</subject>
+ <phone ext="123">318-555-8634</phone>
+ <message><![CDATA[Message content here]]></message>
+ <attachments>
+ <file name="file.txt" type="text/plain"><![CDATA[
+ File content is here and is automatically trimmed
+ ]]></file>
+ <file name="image.gif" type="image/gif" encoding="base64">
+ R0lGODdhMAAwAPAAAAAAAP///ywAAAAAMAAwAAAC8IyPqcvt3wCcDkiLc7C0qwy
+ GHhSWpjQu5yqmCYsapyuvUUlvONmOZtfzgFzByTB10QgxOR0TqBQejhRNzOfkVJ
+ +5YiUqrXF5Y5lKh/DeuNcP5yLWGsEbtLiOSpa/TPg7JpJHxyendzWTBfX0cxOnK
+ PjgBzi4diinWGdkF8kjdfnycQZXZeYGejmJlZeGl9i2icVqaNVailT6F5iJ90m6
+ mvuTS4OK05M0vDk0Q4XUtwvKOzrcd3iq9uisF81M1OIcR7lEewwcLp7tuNNkM3u
+ Nna3F2JQFo97Vriy/Xl4/f1cf5VWzXyym7PHhhx4dbgYKAAA7
+ </file>
+ </attachments>
+ <ip>123.211.233.122</ip>
+</ticket>
+```
### JSON Payload Example ###
-Attachment data for the JSON payload uses the [RFC 2397][] data URL format.
+* `POST /api/tickets.json`
+
+Attachment data for the JSON content uses the [RFC 2397][] data URL format.
As described above, the content-type and base64 encoding hints are optional.
Furthermore, a character set can be optionally declared for each attachment
and will be automatically converted to UTF-8 for database storage.
@@ -77,21 +89,23 @@ denoted with a capital `X`
Do also note that the JSON format forbids a comma after the last element in
an object or array definition, and newlines are not allowed inside strings.
- {
- "alert": true,
- "autorespond": true,
- "source": "API",
- "name": "Peter Rotich",
- "email": "peter@osticket.com",
- "phone": "5043058634X123",
- "subject": "Testing API",
- "ip": "123.211.233.122",
- "message": "MESSAGE HERE",
- "attachments": [
- {"file.txt": "data:text/plain;charset=utf-8,content"},
- {"image.png": "data:image/png;base64,R0lGODdhMAA..."},
- ]
- }
+``` json
+{
+ "alert": true,
+ "autorespond": true,
+ "source": "API",
+ "name": "Angry User",
+ "email": "api@osticket.com",
+ "phone": "3185558634X123",
+ "subject": "Testing API",
+ "ip": "123.211.233.122",
+ "message": "MESSAGE HERE",
+ "attachments": [
+ {"file.txt": "data:text/plain;charset=utf-8,content"},
+ {"image.png": "data:image/png;base64,R0lGODdhMAA..."},
+ ]
+}
+```
[rfc 2397]: http://www.ietf.org/rfc/rfc2397.txt "Data URLs"
@@ -105,7 +119,7 @@ description. Most likely offenders are
* Data type mismatch (text send for numeric field)
* Incorrectly encoded base64 data
* Unsupported field sent
-* Incorrectly formatted payload (bad JSON or XML)
+* Incorrectly formatted content (bad JSON or XML)
Upon success, the content of the response will be the external ticket id of
the newly-created ticket.
--
GitLab