| title | layout | section | breadcrumbs | ||||||
|---|---|---|---|---|---|---|---|---|---|
IronMQ REST/HTTP API |
default |
mq |
|
IronMQ provides a REST/HTTP API to allow you to interact programmatically with your queues on IronMQ.
| URL | HTTP Verb | Purpose |
|---|---|---|
| /projects/{Project ID}/queues | GET | List Message Queues |
| /projects/{Project ID}/queues/{Queue Name} | GET | Get Info About a Message Queue |
| /projects/{Project ID}/queues/{Queue Name} | POST | Update a Message Queue |
| /projects/{Project ID}/queues/{Queue Name} | DELETE | Delete a Message Queue |
| /projects/{Project ID}/queues/{Queue Name}/clear | POST | Clear All Messages from a Queue |
| /projects/{Project ID}/queues/{Queue Name}/messages | POST | Add Messages to a Queue |
| /projects/{Project ID}/queues/{Queue Name}/messages/webhook | POST | Add Messages to a Queue via Webhook |
| /projects/{Project ID}/queues/{Queue Name}/messages | GET | Get Messages from a Queue |
| /projects/{Project ID}/queues/{Queue Name}/messages/peek | GET | Peek Messages on a Queue |
| /projects/{Project ID}/queues/{Queue Name}/messages/{Message ID} | GET | Get Message by ID |
| /projects/{Project ID}/queues/{Queue Name}/messages/{Message ID} | DELETE | Delete a Message from a Queue |
| /projects/{Project ID}/queues/{Queue Name}/messages | DELETE | Delete Multiple Messages from a Queue |
| /projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}/touch | POST | Touch a Message on a Queue |
| /projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}/release | POST | Release a Message on a Queue |
| URL | HTTP Verb | Purpose |
|---|---|---|
| /projects/{Project ID}/queues/{Queue Name}/subscribers | POST | Add Subscribers to a Queue |
| /projects/{Project ID}/queues/{Queue Name}/subscribers | DELETE | Remove Subscribers from a Queue |
| /projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}/subscribers | GET | Get Push Status for a Message |
| /projects/{Project ID}/queues/{Queue Name}/messages/{Message ID}/subscribers/{Subscriber ID} | DELETE | Delete Push Message for a Subscriber |
IronMQ uses OAuth2 tokens to authenticate API requests. All methods require authentication unless specified otherwise. You can find and create your API tokens in the HUD. To authenticate your request, you should include a token in the Authorization header for your request or in your query parameters. Tokens are universal, and can be used across services.
Note that each request also requires a Project ID to specify which project the action will be performed on. You can find your Project IDs in the HUD. Project IDs are also universal, so they can be used across services as well.
Example Authorization Header:
Authorization: OAuth abc4c7c627376858
Example Query with Parameters:
GET https://mq-aws-us-east-1.iron.io/1/projects/{Project ID}/queues?oauth=abc4c7c627376858
Notes:
- Be sure you have the correct case, it's OAuth, not Oauth.
- In URL parameter form, this will be represented as:
?oauth=abc4c7c627376858
Requests to the API are simple HTTP requests against the API endpoints.
All request bodies should be in JSON format, with Content-Type of application/json.
All endpoints should be prefixed with the following:
https://{host}/1
The hosts for the clouds IronMQ supports are as follows:
| Cloud | {host} |
|---|---|
| AWS | mq-aws-us-east-1.iron.io |
| Rackspace ORD | mq-rackspace-ord.iron.io |
| Rackspace DFW Deprecated - please use ORD. |
mq-rackspace-dfw.iron.io |
Alternative domains can be found here in case of dns failures.
For endpoints that return lists/arrays of values:
- page - The page of results to return. Default is 0. Maximum is 100.
- per_page - The number of results to return. It may be less if there aren't enough results. Default is 30. Maximum is 100.
All responses are in JSON, with Content-Type of application/json. A response is structured as follows:
{% highlight js %} { "msg": "some success or error message" } {% endhighlight %}
The success failure for request is indicated by an HTTP status code. A 2xx status code indicates success, whereas a 4xx status code indicates an error.
| Code | Status |
|---|---|
| 200 | OK: Successful GET |
| 201 | Created: Successful POST |
| 400 | Bad Request: Invalid JSON (can't be parsed or has wrong types). |
| 401 | Unauthorized: The OAuth token is either not provided or invalid. |
| 403 | Project suspected, resource limits. |
| 404 | Not Found: The resource, project, or endpoint being requested doesn’t exist. |
| 405 | Invalid HTTP method: A GET, POST, DELETE, or PUT was sent to an endpoint that doesn’t support that particular verb. |
| 406 | Not Acceptable: Required fields are missing. |
| 503 | Service Unavailable. Clients should implement exponential backoff to retry the request. |
Specific endpoints may provide other errors in other situations.
When there's an error, the response body contains a JSON object something like:
{% highlight js %} { "msg": "reason for error" } {% endhighlight %}
When a 503 error code is returned, it signifies that the server is currently unavailable. This means there was a problem processing the request on the server-side; it makes no comment on the validity of the request. Libraries and clients should use exponential backoff when confronted with a 503 error, retrying their request with increasing delays until it succeeds or a maximum number of retries (configured by the client) has been reached.
Get a list of all queues in a project. By default, 30 queues are listed at a time. To see more, use the page parameter or the per_page parameter. Up to 100 queues may be listed on a single page.
- Project ID: Project these queues belong to
- page: The 0-based page to view. The default is 0.
- per_page: The number of queues to return per page. The default is 30, the maximum is 100.
{% highlight js %} [ { "id": "1234567890abcdef12345678", "project_id": "1234567890abcdef12345678", "name": "queue name" } ] {% endhighlight %}
This call gets general information about the queue.
- Project ID: Project the queue belongs to
- Queue Name: Name of the queue
{% highlight js %} { "size": "queue size" } {% endhighlight %}
This call deletes a message queue and all its messages.
- Project ID: Project the queue belongs to
- Queue Name: Name of the queue
{% highlight js %} { "msg": "Deleted." } {% endhighlight %}
This allows you to change the properties of a queue including setting subscribers and the push type if you want it to be a push queue.
- Project ID: Project the queue belongs to
- Queue Name: Name of the queue. If the queue does not exist, it will be created for you.
The following parameters are all related to Push Queues.
- subscribers: An array of subscriber hashes containing a required "url" field and an optional "headers" map for custom headers. This set of subscribers will replace the existing subscribers. See Push Queues to learn more about types of subscribers. To add or remove subscribers, see the add subscribers endpoint or the remove subscribers endpoint. The maximum is 64kb for JSON array of subscribers' hashes. See below for example JSON.
- push_type: Either
multicastto push to all subscribers orunicastto push to one and only one subscriber. Default ismulticast. To revert push queue to reqular pull queue setpull. - retries: How many times to retry on failure. Default is 3. Maximum is 100.
- retries_delay: Delay between each retry in seconds. Default is 60.
- error_queue: The name of another queue where information about messages that can't be delivered after retrying
retriesnumber of times will be placed. Pass in an empty string to disable error queues. Default is disabled. See Push Queues to learn more.
{% highlight js %} { "push_type":"multicast", "subscribers": [ {"url": "http://mysterious-brook-1807.herokuapp.com/ironmq_push_1"}, { "url": "http://mysterious-brook-1807.herokuapp.com/ironmq_push_2", "headers": {"Content-Type": "application/json"} } ] } {% endhighlight %}
{% highlight js %} { "id":"50eb546d3264140e8638a7e5", "name":"pushq-demo-1", "size":7, "total_messages":7, "project_id":"4fd2729368a0197d1102056b", "retries":3, "push_type":"multicast", "retries_delay":60, "subscribers":[ {"url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_1"}, {"url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_2", "headers": {"Content-Type": "application/json"}} ] } {% endhighlight %}
Add subscribers (HTTP endpoints) to a queue. This is for Push Queues only.
- Project ID: Project the queue belongs to
- Queue Name: Name of the queue. If the queue does not exist, it will be created for you.
The following parameters are all related to Push Queues.
- subscribers: An array of subscriber hashes containing a required "url" field and an optional "headers" map for custom headers. See below for example. See Push Queues to learn more about types of subscribers.
{% highlight js %} { "subscribers": [ { "url": "http://mysterious-brook-1807.herokuapp.com/ironmq_push_2", "headers": {"Content-Type": "application/json"} } ] } {% endhighlight %}
{% highlight js %} { "id":"50eb546d3264140e8638a7e5", "name":"pushq-demo-1", "size":7, "total_messages":7, "project_id":"4fd2729368a0197d1102056b", "retries":3, "push_type":"multicast", "retries_delay":60, "subscribers":[ {"url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_1"}, {"url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_2", "headers": {"Content-Type": "application/json"}} ] } {% endhighlight %}
Remove subscriber from a queue. This is for Push Queues only.
- Project ID: Project the queue belongs to
- Queue Name: Name of the queue. If the queue does not exist, it will be created for you.
The following parameters are all related to Push Queues.
- subscribers: An array of subscriber hashes containing a "url" field. See below for example.
{% highlight js %} { "subscribers": [ {"url": "http://mysterious-brook-1807.herokuapp.com/ironmq_push_2"} ] } {% endhighlight %}
{% highlight js %} { "id":"50eb546d3264140e8638a7e5", "name":"pushq-demo-1", "size":7, "total_messages":7, "project_id":"4fd2729368a0197d1102056b", "retries":3, "push_type":"multicast", "retries_delay":60, "subscribers":[ {"url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_1"} ] } {% endhighlight %}
This call deletes all messages on a queue, whether they are reserved or not.
- Project ID: The project these messages belong to.
- Queue Name: The name of the queue.
{% highlight js %} { "msg": "Cleared" } {% endhighlight %}
This call adds or pushes messages onto the queue.
- Project ID: The project these messages belong to.
- Queue Name: The name of the queue. If the queue does not exist, it will be created for you.
Multiple messages may be added in a single request, provided that the messages should all be added to the same queue. Each message object should contain the following keys:
- body: The message data
- timeout: After timeout (in seconds), item will be placed back onto queue. You must delete the message from the queue to ensure it does not go back onto the queue. Default is 60 seconds. Minimum is 30 seconds, and maximum is 86,400 seconds (24 hours).
- delay: The item will not be available on the queue until this many seconds have passed. Default is 0 seconds. Maximum is 604,800 seconds (7 days).
- expires_in: How long in seconds to keep the item on the queue before it is deleted. Default is 604,800 seconds (7 days). Maximum is 2,592,000 seconds (30 days).
{% highlight js %} { "messages": [ { "body": "This is my message 1." }, { "body": "This is my message 2.", "timeout": 30, "delay": 2, "expires_in": 86400 } ] } {% endhighlight %}
{% highlight js %} { "ids": ["message 1 ID", "message 2 ID"], "msg": "Messages put on queue." } {% endhighlight %}
By adding the queue URL below to a third party service that supports webhooks, every webhook event that the third party posts will be added to your queue. The request body as is will be used as the "body" parameter in normal POST to queue above.
- Project ID: The project these messages belong to.
- Queue Name: The name of the queue. If the queue does not exist, it will be created for you.
This call gets/reserves messages from the queue. The messages will not be deleted, but will be reserved until the timeout expires. If the timeout expires before the messages are deleted, the messages will be placed back onto the queue. As a result, be sure to delete the messages after you're done with them.
- Project ID: The Project these messages belong to.
- Queue Name: The name of queue.
- n: The maximum number of messages to get. Default is 1. Maximum is 100. Note: You may not receive all n messages on every request, the more sparse the queue, the less likely you are to receive all n messages.
- timeout: After timeout (in seconds), item will be placed back onto queue. You must delete the message from the queue to ensure it does not go back onto the queue. If not set, value from POST is used. Default is 60 seconds, minimum is 30 seconds, and maximum is 86,400 seconds (24 hours).
{% highlight js %} { "messages": [ { "id": 1, "body": "first message body", "timeout": 600, "reserved_count": 1, "push_status": {"retries_remaining": 1} }, { "id": 2, "body": "second message body", "timeout": 600, "reserved_count": 1, "push_status": {"retries_remaining": 1} } ] } {% endhighlight %}
Peeking at a queue returns the next messages on the queue, but it does not reserve them.
- Project ID: The Project these messages belong to.
- Queue Name: The name of queue.
- n: The maximum number of messages to peek. Default is 1. Maximum is 100. Note: You may not receive all n messages on every request, the more sparse the queue, the less likely you are to receive all n messages.
{% highlight js %} { "messages": [ { "id": 1, "body": "first message body", "timeout": 600 }, { "id": 2, "body": "second message body", "timeout": 600 } ], } {% endhighlight %}
Get a message by ID.
- Project ID: The Project these messages belong to.
- Queue Name: The name of queue.
- Message ID: The id of the message to release.
{% highlight js %} { "id": "5924625841136130921", "body": "hello 265", "timeout": 60, "reserved_count": 1 } {% endhighlight %}
Releasing a reserved message unreserves the message and puts it back on the queue as if the message had timed out.
- Project ID: The project these messages belong to.
- Queue Name: The name of queue.
- Message ID: The id of the message to release.
- delay: The item will not be available on the queue until this many seconds have passed. Default is 0 seconds. Maximum is 604,800 seconds (7 days).
{% highlight js %} { "delay": 60 } {% endhighlight %}
A JSON document body is required even if all parameters are omitted.
{% highlight js %} {} {% endhighlight %}
{% highlight js %} { "msg": "Released" } {% endhighlight %}
Touching a reserved message extends its timeout to the duration specified when the message was created. Default is 60 seconds.
- Project ID: The project these messages belong to.
- Queue Name: The name of queue.
- Message ID: The id of the message to touch.
Any empty JSON body.
{% highlight js %} {} {% endhighlight %}
{% highlight js %} { "msg": "Touched" } {% endhighlight %}
This call will delete the message. Be sure you call this after you're done with a message or it will be placed back on the queue.
- Project ID: The project these messages belong to.
- Queue Name: The name of queue.
- Message ID: The id of the message to delete.
{% highlight js %} { "msg": "Deleted" } {% endhighlight %}
This call will delete multiple messages in one call.
- Project ID: The project these messages belong to.
- Queue Name: The name of queue.
- ids: An array of message ids as string.
{% highlight js %} { "ids": [ "MESSAGE_ID_1", "MESSAGE_ID_2" ] } {% endhighlight %}
{% highlight js %} { "msg": "Deleted" } {% endhighlight %}
You can retrieve the push status for a particular message which will let you know which subscribers have received the message, which have failed, how many times it's tried to be delivered and the status code returned from the endpoint.
- Project ID: The project these messages belong to.
- Queue Name: The name of queue.
- Message ID: The id of the message to retrieve status for.
{% highlight js %} { "subscribers":[ { "retries_delay":60, "retries_remaining":2, "status_code":200, "status":"deleted", "url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_2", "id":"5831237764476661217" }, { "retries_delay":60, "retries_remaining":2, "status_code":200, "status":"deleted", "url":"http://mysterious-brook-1807.herokuapp.com/ironmq_push_1", "id":"5831237764476661218" } ] } {% endhighlight %}
This is only for use with long running processes that have previously returned a 202. Read Push Queues page for more information on Long Running Processes
- Project ID: The project these messages belong to.
- Queue Name: The name of queue.
- Message ID: The id of the message.
- Subscriber ID: The id of the subscriber to delete.
{% highlight js %} { "msg": "Deleted" } {% endhighlight %}