Note: These sections are in development and not currently released
bigWebApps HelpDesk API
The api allows developers to access bigWebApps HelpDesk data programmatically via JSON.
Service URL
https:// SSL connections are required.
base server:
https://api.helpdesk.bigwebapps.com/
full:
https://api.helpdesk.bigwebapps.com/{orgKey}/{instanceKey}/{object}/{objectKey}...
e.g.:
https://api.helpdesk.bigwebapps.com/ys2g62/hd7w3e/tickets/kh2s3z/...
App Key
App Keys are free and easy to obtain. Currently email support@bigwebapps.com to obtain an app key, include: developer name, email, company name, company website, phone, company email. The App Key uses the same 6 character system we use for Pseudo Unique values. e.g. hsy2sd2
Organization Level Authentication
Use basic authentication over SSL. Username in a concatenated string of Org and InstanceId. It is used to identify your organization and database. Password is an API key generated inside the web application. Both username and password can be found at Configuration > API Keys. App Key is a 36 character hyphenated guid string to identify the requesting application in the API calls, requires registration by each app developer to obtain one key per app.
GET /{orgKey}/{instanceKey}/tickets/{objectKey} HTTP/1.1
Host: api.helpdesk.bigwebapps.com:443
Authorization: Basic {appKey}:{APIKeyString}
e.g
GET /skfw2s/s2fq3f/tickets/dhzs3sz HTTP/1.1
Host:api.helpdesk.bigwebapps.com:443
Authorization: Basic e1f965:c18023a0-9b1e-4007-8ce1-7578a925164f
User Level Authentication
Users may be associated to more than one organization and more than one database instance in each organization. You should query the API to return a list of the user’s organizations and database instances.
Get List of User’s Database Instances
GET /security/instances/ HTTP/1.1
Host: api.helpdesk.bigwebapps.com:443
Authorization: Basic {appKey},{userLogin/Email}:{password}
e.g.
GET /security/instances/ HTTP/1.1
Host: api.helpdesk.bigwebapps.com:443
Authorization: Basic e1f965,jon@acme.com:12345
Response
HTTP/1.1 200 OK
Content-Type: application/json
[{"org-key":"hfh23d","org-name":"Acme Inc","key":"nmase3","name":"Tech Dept"},
{"org-key":"hfh23d","org-name":"Acme Inc","key":"82hnzw","name":"Maint Dept"},
{"org-key":"wf2s38","org-name":"Wayne Ent","key":"","72hwxs":"Default"}]
Follow-up Requests
Use the Organization and Instance Keys to form the base URL for each request.
GET /njsdfh/72hwxs/tickets/wes428/ HTTP/1.1 Host: api.helpdesk.bigwebapps.com:443 Authorization: Basic e1f965,jon@acme.com:12345
Field Naming
Bit – Boolean
Field names can have present or past tense and have the prefix “is-“. e.g. is-active, is-enabled, is-created
Values are 1 (true), 0 (false), “null” (null)
Dates | no time
Format is YYYY-MM-DD
Date fields are in past tense and have the suffix “-date”. e.g. created-date, updated-date, sent-date.
Time
Format is YYYY-MM-DDThh:mm:ss.sTZD (refer to W3C ISO 8601)
Time fields are in the past tense and have the suffix “-time”. e.g created-time, updated-time, sent-time
Examples below are the same date and time.
1994-11-05T08:15:30-05:00
1994-11-05T13:15:30Z
User Foreign Key References
Have the suffix “-userid”. e.g. user-userid, tech-userid, created-userid, created-userid.
HTTP Verbs
GET
Safe, Idempotent implied.
POST
Non Idempotent, multiple requests can generate duplicate objects. The ID (int/guid) is generated by the server. The location of the object is returned as part of the response. Most similar to CRUD – CREATE statement.
PUT
Idempotent, multiple identical requests should have the same effect. The ID (int/guid) is generated client side and specified in the data transferred to the server. The resource is placed in its final position during the PUT request. Most similar to CRUD – UPDATE statement. If the object exists, replace the entire object with the uploaded data.
DELETE
Idempotent, multiple identical requests should have the same effect.
JSONP CallBacks
Callbacks are needed for users implementing JSONP. Using the “jsonp” callback parameter you are instructing our web service end point to wrap the json output in a javascript function. Remember JSONP only supports HTTP GET requests.
?jsonp=FUNC_NAME e.g. https://api.helpdesk.bigwebapps.com/ticket/1?jsonp=HelloWorld
a standard JSON Response
{"symbol" : "IBM", "price" : 91.42}
a JSONP Response with CallBack
HelloWorld({"symbol" : "IBM", "price" : 91.42})
HTML Return Codes
General Codes
1xx – Informational: Request received, continuing process.
2xx – Success: Action successfully received, understood, and accepted.
3xx – Redirection: Client must take additional action to complete the request.
4xx – Client Error: Request contains bad syntax or cannot be fulfilled
5xx – Server Error: Server failed to fulfill an apparently valid request.
Specific Codes
| 200 | OK | Represents a successful transaction |
| 201 | Created & Location | Used during POST operation to represent a successful transaction and return the absolute URI of the new resource in the HTTP Location header. |
| 204 | No Content | Request was valid, no content is returned. Empty search results. |
| 400 | Bad Request | The request was invalid. An accompanying error message will explain the reason. |
| 401 | Unauthorized | Authentication were missing or incorrect. |
| 403 | Forbidden | The request was understood, but it has been refused. An accompanying error message will explain the reason. |
| 404 | Not Found | The URI requested is invalid or the resource requested does not exist |
| 405 | Method Not Allowed | The HTTP Method is not allowed on the resource. For example, if you attempt to post to URL which does not support POST. |
| 420 | Rate Limit | Your api key is being rate limited. |
| 500 | Internal Server Error | Something is broken. Please post to the forum for investigation. |
| 502 | Bad Gateway | Service is in a known down state or being upgraded. |
Request Limits
API requests are limited to 300 requests per hour.
Pseudo Unique Values
Keys used on some resources in place of ID int or guid. Pseudo Unique values are 6 character strings consisting of random alpha numeric values 0-9 and lower case letters a-z (excluding “o”). e.g. jkl2dz, 23jrea. There are 35 character combinations.
Pages
API requests which return multiple objects are limited to 25 records per page. Page numbers start at 1. If your results contain 25 objects you should inspect the next page for additional objects. Use the query string “pg=2″.
/ticket?pg=2
Error Messages
Details of error or missing data can be found in the Json data payload.
HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: xxxx
{"error":"Missing the user or class to transfer the ticket."}
Samples
JSON Request Single Resource
GET /tickets/GJU453S/ HTTP/1.1 Accept: application/json Host: api.helpdesk.bigwebapps.com:443
Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxxx
{"id":"xxxxx","priority":7,"subject"="My Printer is Broken!"}
JSON Request Query Multiple Return Records
GET /tickets?status=open&priority=2 HTTP/1.1 Accept: application/json Host: api.helpdesk.bigwebapps.com:443
Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxxx
[
{"id":"xxxxx","priority":1,"subject":"My Printer is Broken!"},
{"id":”yyyy","priority":2,"subject":"I forgot my password"}
]
