IronMQ v3 API Reference

IronMQ v3 has made a few improvements over our previous API. This reference is a continuing work in progress

Changes
Basics
Global Stuff
Queues
Create Queue
Get Queue
Update Queue
Delete Queue
List Queues
Add or Update Subscribers
Replace Subscribers
Remove Subscribers
Messages
Post Messages - Core operation to add messages to a queue
Post Messages via Webhook
Reserve/Get Messages - Core operation to get message(s) off the queue.
Get Message by Id
Peek Messages - View first messages in queue without reserving them
Delete Message - Core operation to delete a message after it’s been processed
Delete Messages - Batch delete
Release Message - Makes a message available for another process
Touch Message - Extends the timeout period so process can finish processing message
Clear Messages - Removes all messages from a queue
Get Push Statuses for a Message

Changes

Changes from v2.0.1:

Dequeue now returns a reservation. This reservation_id and message_id are required to perform any action (ie deleting, touching, releasing). The reservation is valid for the length of the message timeout (inherited from the queues timeout) unless a timeout was specified on the dequeue call.
Expiration and timeout can no longer be set when queueing a message.
Timed out and released messages go to the front of the queue. (This is not an API change, but it is a behavior change that will likely cause some tests to fail.)
Push queues must be explicitly created. There’s no changing a queue’s type.
All json objects are wrapped at the root level.
All object structures changed a bit, please review json.
Clear messages endpoint changed to be part of delete messages.
Can no longer set timeout when posting a message, only when reserving one.
Webhook url is no longer /queues/{Queue Name}/messages/webhook, it is now /queues/{Queue Name}/webhook
Pagination principle in List Queues changed. It doesn’t support page parameter. You should specify the name of queue prior to the first desirable queue in result.
Trying to get messages from a queue that doesn’t exist now returns a “Queue not found” error.

Basics

Typical usage and lifecycle for a message is post-reserve-delete.

If you are moving from v2 to v3, this is slightly different from the previous post-get-delete. First, Make sure to update your client library from v2 to v3. For now, each library has a v3 branch that you should use for this api. The v2 libraries will not work for the v3 api. You will also need new credentials, which you can obtain through https://www.iron.io/signup. Your v2 credentials (iron.json, et al) will not work with v3.

It is very important not to conflate Get and Reserve. In typical usage, Get is unnecessary, and in terms of the v2 API, Get has been replaced by Reserve. This change has been reflected in the client libraries, as well as the api. It is also important not to use Peek or Get in order to process messages, these endpoints should be used as strictly informative, since they do not guarantee sole access to a message for a given period of time.

Typical usage for pull queues in pseudo-ruby is below. Other languages will have similar method and type names.

# get a handle on the queue
q = queue("my_queue")

# post a message to the queue
q.Post("some message")

# reserve a message from the queue for 60s (default)
msg = q.Reserve(1)

# process the message in your application

# when you're done, try to delete the message with the reservation_id
q.Delete(:id => msg.id, :reservation_id => msg.reservation_id)

A common error to get back from q.Delete is a 403: Reservation timed out. This means that the message has timed out and has been put back onto the queue. In order to delete the message, you will need a new reservation_id, which you can only get by reserving the message again.

For some applications, it can be okay to process the message twice (idempotent operations, etc.). If the reservations are timing out frequently, we would recommend to raise the timeouts on the queue, 120 [seconds] is usually enough if the timeouts are intermittent. If you are using batching in your consumers, we also recommend raising the timeouts.

Another issue is 401: Unauthorized. This probably means you are attempting to use v2 credentials for v3. To get v3 credentials, go to www.iron.io/signup.

If you need any more support or are having any other issues, feel free to contact support@iron.io including any relevant information.

Global Stuff

Base path: /3/projects/{Project ID}

All requests:

Headers:

Content-Type: application/json

Authentication

Headers:

Authorization: OAuth TOKEN

Queues

Create Queue

PUT /queues/{Queue Name}

Request:

All fields are optional.

type can be one of: [multicast, unicast, pull] where multicast and unicast define push queues. default is pull

If push field is defined, this queue will be created as a push queue and must contain at least one subscriber. Everything else in the push map is optional.

If dead_letter field is defined, queue_name must not be an empty string. max_reservations will default to 10 if unspecified. 1 <= max_reservations <= 1000. dead_letter can not be specified on a push queue, use error_queue instead.

{
  "queue": {
    "message_timeout": 60,
    "message_expiration": 3600,
    "type": "pull/unicast/multicast",
    "push": {
      "subscribers": [
        {
          "name": "subscriber_name",
          "url": "http://mysterious-brook-1807.herokuapp.com/ironmq_push_1",
          "headers": {"Content-Type": "application/json"}
        }
      ],
      "retries": 3,
      "retries_delay": 60,
      "error_queue": "error_queue_name"
    },
    "dead_letter": {
      "queue_name": "dlq",
      "max_reservations": 10
    }
  }
}

Response: 200 OK

same as Get Queue except that size and total_messages fields are missing

Get Queue Info

GET /queues/{Queue Name}

Response: 200 or 404

Some fields will not be included if they are not applicable like push if it’s not a push queue and alerts if there are no alerts.

{
  "queue": {
    "project_id": 123,
    "name": "my_queue",
    "size": 0,
    "total_messages": 0,
    "message_timeout": 60,
    "message_expiration": 604800,
    "type": "pull/unicast/multicast",
    "push": {
      "subscribers": [
        {
          "name": "subscriber_name",
          "url": "http://mysterious-brook-1807.herokuapp.com/ironmq_push_1",
          "headers": {
            "Content-Type": "application/json"
          }
        }
      ],
      "retries": 3,
      "retries_delay": 60,
      "error_queue": "error_queue_name"
    }
  }
}

Update Queue

PATCH /queues/{Queue Name}

Request:

SAME AS CREATE QUEUE, except queue type, which is static.

Note: API raises error when you try to set subscribers to pull type queue or alerts on push queue.

Response: 200 or 404

Some fields will not be included if they are not applicable like push if it’s not a push queue and alerts if there are no alerts.

SAME AS GET QUEUE INFO

Delete Queue

DELETE /queues/{Queue Name}

Response: 200 or 404

{
  "msg": "Deleted"
}

List Queues

GET /queues

Lists queues in alphabetical order.

Request URL Query Parameters:

per_page: number of elements in response, default is 30.
previous: this is the last queue on the previous page, it will start from the next one. If queue with specified name doesn’t exist result will contain first per_page queues that lexicographically greater than previous
prefix: an optional queue prefix to search on. e.g., prefix=ca could return queues [“cars”, “cats”, etc.]

Response: 200 or 404

{
  "queues": [
    {
      "name": "queue_name_here"
    },
    {
      "name": "another_queue_name"
    }
  ]
}

Add or Update Subscribers to a Queue

POST /queues/{Queue Name}/subscribers

Add subscribers (HTTP endpoints) to a queue. In the case subscriber with given name exists, it will be updated.

Request:

{
  "subscribers": [
    {
      "name": "first",
      "url": "http://mysterious-brook-1807.herokuapp.com/ironmq_push_2",
      "headers": {
        "Content-Type": "application/json"
      }
    },
    {
      "name": "other",
      "url": "http://this.host.is/not/exist"
    }
  ]
}

Response:

{
  "msg": "Updated"
}

Replace Subscribers on a Queue

PUT /queues/{Queue Name}/subscribers

Sets list of subscribers to a queue. Older subscribers will be removed.

Request:

{
  "subscribers": [
    {
      "name": "the_only",
      "url": "http://my.over9k.host.com/push"
    }
  ]
}

Response:

{
  "msg": "Updated"
}

Remove Subscribers from a Queue

DELETE /queues/{Queue Name}/subscribers

Remove subscriber from a queue. This is for Push Queues only.

Request:

{
  "subscribers": [
    {
      "name": "other"
    }
  ]
}

Response:

{
  "msg": "Updated"
}

Messages

Post Messages

POST /queues/{Queue Name}/messages

Message Object

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:

Required

body: The message data

Optional

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).

Request:

{
  "messages": [
    {
      "body": "This is my message 1.",
      "delay": 0,
      "push_headers": {
        "X-Custom-Header": "custom header value",
        "Authentication": "the token"
      }
    }
  ]
}

Response: 201 Created

Returns a list of message ids in the same order as they were sent in.

{
  "ids": [
    "2605601678238811215"
  ],
  "msg": "Messages put on queue."
}

Push Headers Restrictions

the maximum number of push headers per message is 5
push header name cannot be empty
the maximum length of push header name is 64 bytes
push header name cannot be any of Content-Type, User-Agent, Iron-Message-Id, Iron-Reservation-Id, Iron-Subscriber-Name, Iron-Subscriber-Message-Url
push header value cannot be empty
the maximum length of header value is 1kb

If request contravenes restrictions, IronMQ responds with HTTP 400 Bad Request.

Post Messages via Webhook

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.

Push Headers

It is possible to supply custom push headers for messages, posted via webhook. IronMQ treats headers, which start with X-Subscribers- prefix, as push headers. Prefix will be removed and reminder will be used as actual header name.

NOTE: push headers, that contravene restrictions (see Post Messages section), will be ignored and error will not be raised.

Endpoint

POST /queues/{Queue Name}/webhook

URL Parameters

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.

Reserve Messages

POST /queues/{Queue Name}/reservations

Request:

All fields are optional.

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 queue is used. Default is 60 seconds, minimum is 30 seconds, and maximum is 86,400 seconds (24 hours).
wait: Time to long poll for messages, in seconds. Max is 30 seconds. Default 0.
delete: If true, do not put each message back on to the queue after reserving. Default false.

{
  "n": 1,
  "timeout": 60,
  "wait": 0,
  "delete": false
}

Response: 200

{
  "messages": [
    {
       "id": 123,
       "body": "this is the body",
       "reserved_count": 1,
       "reservation_id": "def456"
    },
  ]
}

Will return an empty array if no messages are available in queue.

Get Message by Id

GET /queues/{Queue Name}/messages/{Message ID}

Response: 200

{
  "message": {
    "id": 123,
    "body": "This is my message 1.",
    "reserved_count": 1    
  }
}

Peek Messages

GET /queues/{Queue Name}/messages

Request:

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.

Response: 200

Some fields will not be included if they are not applicable like push if it’s not a push queue and alerts if there are no alerts.

{
  "messages": [
    {
       "id": 123,
       "body": "message body",
       "reserved_count": 1
    },
  ]
}

Delete Message

DELETE /queues/{Queue Name}/messages/{Message ID}

Request:

reservation_id: This id is returned when you reserve a message and must be provided to delete a message that is reserved. If a reservation times out, this will return an error when deleting so the consumer knows that some other consumer will be processing this message and can rollback or react accordingly. If the message isn’t reserved, it can be deleted without the reservation_id.
subscriber_name: This field could be used in case of push message processing acknowledge. When request from IronMQ Pusher is received, and subscriber endpoint returns HTTP 202 Accepted, message must be acknowledged, otherwise it will be pushed again (if retries are configured). Send both reservation_id and subscriber_name to acknowledge processed message.

{
  "reservation_id": "def456"
}

Response: 200 or 404

{
  "msg": "Deleted"
}

Delete Messages

DELETE /queues/{Queue Name}/messages

This is for batch deleting messages. Maximum number of messages you can delete at once is 100.

Request:

reservation_id: This id is returned when you reserve a message and must be provided to delete a message that is reserved. If a reservation times out, this will return an error when deleting so the worker knows that some other worker will be processing this message and can rollback or react accordingly.
subscriber_name: This field could be used in case of push message processing acknowledge. When request from IronMQ Pusher is received, and subscriber endpoint returns HTTP 202 Accepted, message must be acknowledged, otherwise it will be pushed again (if retries are configured). Send both reservation_id and subscriber_name to acknowledge processed message.

{
  "ids": [
    {
      "id": 123,
      "reservation_id": "abc"
    },
  ]
}

Response: 200 or 404

{
  "msg": "Deleted"
}

Touch Message

POST /queues/{Queue Name}/messages/{Message ID}/touch

This request creates new reservation for a message. It requires valid reservation_id, and returns new reservation_id for the message.

Request:

reservation_id: appropriate message’s reservation ID.
timeout: optional. How many seconds new reservation will be valid. Defaults to queue’s message_timeout option.

{
  "reservation_id": "5259a40cf166faa76a23f7450daaf497",
  "timeout": 120
}

Response: 200 or 404

{
  "reservation_id": "5359a40cf166faa76a23f7450daaffff",
  "msg": "Touched"
}

Release Message

POST /queues/{Queue Name}/messages/{Message ID}/release

Request:

{
  "reservation_id": "5359a40cf166faa76a23f7450daaffff",
  "delay": 60
}

Response: 200 or 404

{
  "msg": "Released"
}

Clear Messages

DELETE /queues/{Queue Name}/messages

This will remove all messages from a queue.

Request:

{}

Response: 200 or 404

{
  "msg": "Cleared"
}

Get Push Statuses for a Message

GET /queues/{Queue Name}/messages/{Message ID}/subscribers

You can retrieve the push statuses 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.

Response:

{
  "subscribers": [
    {
      "name": "first",
      "retries_remaining": 2,
      "tries": 1,
      "status_code": 200,
      "url": "http://mysterious-brook-1807.herokuapp.com/ironmq_push_2",
      "last_try_at": "2014-07-30T15:45:03Z"
    },
    {
      "name": "other",
      "retries_remaining": 2,
      "tries": 6,
      "status_code": 200,
      "url": "http://this.host.is/not/exist",
      "last_try_at": "2014-07-30T15:44:29Z"
    }
  ]
}

IronMQ v3 API Reference

Contents

Changes

Basics

Global Stuff

Queues

Create Queue

Get Queue Info

Update Queue

Delete Queue

List Queues

Add or Update Subscribers to a Queue

Replace Subscribers on a Queue

Remove Subscribers from a Queue

Messages

Post Messages

Message Object

Required

Optional

Push Headers Restrictions

Post Messages via Webhook

Push Headers

Endpoint

URL Parameters

Reserve Messages

Get Message by Id

Peek Messages

Delete Message

Delete Messages

Touch Message

Release Message

Clear Messages

Get Push Statuses for a Message

Learn

Develop

Follow