Skip to content
Snippets Groups Projects
Commit 55a8cc26 authored by Jared Hancock's avatar Jared Hancock
Browse files

Add more polish to the API docs

parent b89db568
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
setup/doc/api.md
+ 5
− 0
View file @ 55a8cc26
......@@ -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
--------
......
setup/doc/api/tickets.md
+ 55
− 41
View file @ 55a8cc26
......@@ -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.
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment