Security

Security is based on a Google Login to the application.  The user must be authenticated with Google to Create, Delete, and List Queues.  Pushing, popping, listing items, emptying queues use the queue password if one exists.  Otherwise, the queue is "open" and no authentication is needed. 

Access to the API and authentication can be done using various methods, such as ClientLogin, and retrieving the Auth token as a cookie.  There are many documents explaining how to authenticate to Google Services using various tools and languages.

Base URI

All calls start with the base URI of http://quist.tahelpya.com

Errors

If items are not found, error 404 will be returned.  If no permissions or password incorrect, error 402 will be returned.

Explanation of Queues

The queue system operates as you would expect any traditional queue.  There are some exceptions to a standard queue.  Items are pushed into the queue and popped on a FIFO basis.  Generally, when an item is popped, it is suppressed for a period of time unless explicitly deleted during the pop or with the delete API POST request.  The suppression time is set when the item is pushed into the queue.  Default value is 30 seconds.  The next item in the queue that has not been popped before or is no longer being suppressed will be the next item popped on subsequent pop requests.  Therefore, items that have been popped before may reappear when their suppression times elapse.

Further, an availability may be set, which determines how long an item will be popped (at the top) before it is suppressed.  What this means is an item can be popped by several requests for a period of time before the next item in the queue appears, making that item available to several requestors initially.  The availability expiration check is done once.  The item will behave as if no availability time has been sent when it reappears after the suppression time elapses.

---

Create Queue

Creates a new queue for the authenticated Google account.

URI : /api/queue/create

Parameters:

name - The name of the new queue
password  - A password for accessing the queue (optional)

Example : /api/queue/create?name=My new queue&password=mypassword

Result : The queue ID to be used in subsequent calls to the queue.

---

Push

Push an item into the queue.

URI : /api/queue/push

Parameters:

queue_id - The ID of the queue to push the item into.
password - The queue password if it exists (MD5 of original clear-text password that was given on queue creation).
light_payload - A 512 byte string payload.
heavy_payload - A much larger string blob.
expires_in - Number of seconds to expire the item.  The item will be deleted after expiration and not available for Pop requests (default : 120)
suppress_time - Number of seconds to suppress the item after it is popped.  The item will not be available for Pop requests until this expires (default : 30)
available_time - Number of seconds to make the item available before it is suppressed (default : 0).

Example : /api/queue/push?queue_id=4&light_payload=Here is my payload string&suppress_time=120

Result : The queue item ID.

---

Pop

Pop an item from the queue.  The next item in the queue will be returned.  This is determined by when it was added to the queue (FIFO), if it is not currently suppressed, and if not expired.  Suppressed items will be at the top again after their suppression time is expired. 

URI : /api/queue/pop

Parameters :

queue_id - The ID of the queue to pop the item from.
password - The queue password if it exists (MD5 of original clear-text password).
delete_item - Pass "true" if you want the item to be deleted immediately after popping.  If not passed or "false", the item will be suppressed based on its suppression time.

Examples :

No deletion, item is suppressed: /api/queue/pop?queue_id=4

Item is deleted after pop: /api/queue/pop?queue_id=4&delete_item=true

Result : JSON string representing the queue item.  Example:

{"key":"agVxdWlzdHIPCxIJUXVldWVJdGVtGBMM","heavy_payload":"","created_on":"2008/12/17 18:25:52 +0000","light_payload":"Here is my message","id":"19"}

---

Delete Item

Delete a queue item from the queue.

URI: /api/queue/delete

Parameters:

queue_id - The ID of the queue to pop the item from.
password - The queue password if it exists (MD5 of original clear-text password).
item_id - The ID of the item to delete.

Examples:

/api/queue/delete?queue_id=4&password=098f6bcd4621d373cade4e832627b4f6&item_id=2345

Result : 200 OK

---

Delete Queue

Delete a queue and all items currently in the queue.  Must be authenticated with Google.

URI : /api/queues/delete
note: the use of plural for queues, different than singular which deletes a queue item

Parameters :

queue_id - The queue to delete.

Example : /api/queues/delete?queue_id=4

Result : The number of items deleted before the queue was deleted.

---

List Items

List all items currently in the given queue.

URI : /api/queue/list

Parameters :

queue_id - The queue to list.
password - The queue password if it exists (MD5 of original clear-text password).

Example : /api/queue/list?queue_id=4

Result : JSON string with the items.  Example :

{"items":[{"key":"agVxdWlzdHIPCxIJUXVldWVJdGVtGBMM","popped_on":"2008/12/17 18:26:02 +0000","heavy_payload":"","expires_in":120,"is_suppressed":"False","created_on":"2008/12/17 18:25:52 +0000","light_payload":"Here is my message","is_expired":"True","id":"19"},{"key":"agVxdWlzdHIPCxIJUXVldWVJdGVtGBQM","popped_on":"None","heavy_payload":"","expires_in":120,"is_suppressed":"False","created_on":"2008/12/17 18:29:33 +0000","light_payload":"Here is my message","is_expired":"False","id":"20"},{"key":"agVxdWlzdHIPCxIJUXVldWVJdGVtGBUM","popped_on":"None","heavy_payload":"","expires_in":120,"is_suppressed":"False","created_on":"2008/12/17 18:29:35 +0000","light_payload":"Here is my message","is_expired":"False","id":"21"}],"queue_key":"agVxdWlzdHILCxIFUXVldWUYEgw","queue_id":"18"}

---

Empty Queue

Empty all items from the queue.

URI : /api/queue/empty

Parameters :

queue_id - The queue to empty.
password - The queue password if it exists (MD5 of original clear-text password).

Example : /api/queue/empty?queue_id=4

Result : The number of items emptied.

---

List Queues

List all queues created by the authenticated google account.

URI : /api/queues

Parameters :

Example : /api/queues

Result : JSON list of queues.  Example :

{"queues":[{"created_on":"2008/12/17 18:25:40 +0000","queue_key":"agVxdWlzdHILCxIFUXVldWUYEgw","name":"Test queue","created_by":"bvelasquez","queue_id":"18"}]}