Message queue

Discover and retrieve service messages from the REST API Gateway. Service messages are part of ST Registry collections. For more details about collections please refer to collections article.

GET Read messages queue

GET /notifications/?do=search&field[ntDate][eq]=null&sort_field=crDate&sort_direction=desc&limit=2&offset=0

This command is used to discover and retrieve service messages queued by ST Registry. Each response returned from the server will include a server-unique message identifier, which will be required for acknowledging the receipt of a message. A counter exists to indicate the number of messages in the queue. After a client has received a message, the client MUST respond to the message with an explicit acknowledgement to confirm that the message has been received to make the next message in the queue (if any) available for retrieval. Message acknowledgement mark message as read and do not remove it completely from a queue. All messages (both read and unread) are removed from queue once they become 30 days old.

Fetching unread messages:

Name	Description
do	Identify action that should be performed to collection. For querying messages queue it will be always value “search”.
field	Collection of fields that should using for filtering query result. Field ntDate identify when message was acknowledged, eq – means equal, “null” value identify unread messages. For more details about collections please refer to collections article.
sort_field	Identify message attribute which should be used for sorting results.
sort_direction	Sorting direction. May acquire values: asc or desc (ascending or descending).
limit	Messages limit in response. In other words – number of messages to fetch starting from “offset” position.
offset	Identify how many messages should be skipped before starting fetching messages.

To fetch all messages (both read and unread) – filter for ntDate should be removed from request.

To fetch read messages – filter value for ntDate should be timestamp. It is possible to filter result by date range by using “lt” (less than) and/or “gt” (greater than) instruction instead or “eq” in our example. To read more about collections management please refer to the collections article.

After successful request, response will contain following elements:

id – Message ID. Should be used to acknowledge message (mark as read).
type – message type. Please refer to registrars notification system for complete type of messages.
message – full service message.
clID – client ID who owns this message. Normally this is same client who request message.
crDate – date and time when corresponding message was created.
ntDate – date and time when corresponding message was acknowledged.
object – identify to what kind of object current service message is related. Can obtain values: domain, contact, host.
objID – objectID
data – information related to the service message. Please refer to registrars notification system article for complete list of data formats.
searchInf/limit – requested result limits
searchInf/offset – requested result offset
searchInf/rows_count – total rows count according to applied filter values.
code – response code. 1000 if operation successful.
message – response message. Generally its a description for response code.
cltrid – client transaction ID which was provided in request.
svtrid – server transaction ID which was generated by ST Registry for corresponding request.
time – request execution time in seconds.

Message attributes without values are not reflected in response (like ntDate in this example).

Request Example

GET /notifications/?do=search&field[ntDate][eq]=null&sort_field=crDate&sort_direction=desc&limit=2&offset=0 HTTP/1.1
Host: apihost
Content-Type: application/json
Api-Version: 1.0
Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2
Api-ClientToken: 1a2B3C4d5e6F

Response Example

HTTP/1.1 200 OK
Date: Tue, 01 Jan 2014 00:00:01 GMT
Server: Apache/2.2.15 (CentOS)
X-Powered-By: PHP/5.4.11
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json

{
    "searchRes": {
        "12345": {
            "id": "12345",
            "type": "TRANSFER_REQUEST",
            "message": "Transfer request",
            "clID": "MsgOwnerClientID",
            "crDate": "2014-01-23T14:31:37+00:00",
            "object": "domain",
            "objId": "example1.st",
            "data": {
                "trnData": {
                    "trStatus": "pending",
                    "reID": "GainingClientID",
                    "reName": "GainingClientPublicName",
                    "reDate": "2014-01-23T14:31:37+00:00",
                    "acID": "LoosingClientID",
                    "acName": "LoosingClientPublicName",
                    "acDate": "2014-01-23T14:31:37+00:00",
                    "crDate": "2013-01-22T17:51:05+00:00",
                    "exDate": "2016-01-22T17:51:05+00:00"
                },
                "panData": {
                    "name": "example1.st",
                    "paResult": 1,
                    "paDate": "2014-01-23T14:31:37+00:00",
                    "paTRID": {
                        "clTRID": "TR_TR_DOMAIN",
                        "svTRID": "d720b6f8-a00e-44a5-9bad-f20ef66f2138"
                    }
                }
            }
        },
        "12346": {
            "id": "12346",
            "type": "TRANSFER_CANCEL",
            "message": "Transfer canceled",
            "clID": "MsgOwnerClientID",
            "crDate": "2014-01-23T14:33:22+00:00",
            "object": "domain",
            "objId": "example2.st",
            "data": {
                "trnData": {
                    "trStatus": "clientCancelled",
                    "reID": "GainingClientID",
                    "reName": "GainingClientPublicName",
                    "reDate": "2014-01-23T14:31:37+00:00",
                    "acID": "LoosingClientID",
                    "acName": "LoosingClientPublicName",
                    "acDate": "2014-01-23T14:31:37+00:00",
                    "crDate": "2013-01-22T17:51:05+00:00",
                    "exDate": "2016-01-22T17:51:05+00:00"
                },
                "panData": {
                    "name": "example2.st",
                    "paResult": 1,
                    "paDate": "2014-01-23T14:33:22+00:00",
                    "paTRID": {
                        "clTRID": "TR_TR_DOMAIN",
                        "svTRID": "f3f949be-1dba-45c7-9916-7e45c04de0a5"
                    }
                }
            }
        }
    },
    "searchInf": {
        "limit": 2,
        "offset": 0,
        "rows_count": "7"
    },
    "code": 1000,
    "message": "OK",
    "cltrid": "9a6c67e4-d666-54a8-9465-4847bee812e2",
    "svtrid": "e47ec634-a84e-4922-b97f-15f637b4135e",
    "time": 0.0093629360198975
}

POST Acknowledge Message

POST /notifications/:id:/read

In REST API message acknowledgement perform message marking as read. Such messages are still stored on registry side for some time and later on completely wiped our.

Message acknowledgement is performed for specific message which is identified by its ID.

Name	Description
id	Message identifier for acknowledgement.

After successful request, response will contain following elements:

ntDate – date and time when corresponding message was acknowledged.
code – response code. 1000 if operation successful.
message – response message. Generally its a description for response code.
cltrid – client transaction ID which was provided in request.
svtrid – server transaction ID which was generated by ST Registry for corresponding request.
time – request execution time in seconds.

Request Example

POST /notifications/12345/read HTTP/1.1
Host: apihost
Content-Type: application/json
Api-Version: 1.0
Api-ClientTransactionId: 9a6c67e4-d666-54a8-9465-4847bee812e2
Api-ClientToken: 1a2B3C4d5e6F

Response Example

HTTP/1.1 200 OK
Date: Tue, 01 Jan 2014 00:00:01 GMT
Server: Apache/2.2.15 (CentOS)
X-Powered-By: PHP/5.4.11
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json

{
ntDate: "2014-01-08T16:49:14+00:00"
code: 1000
message: "OK"
cltrid: "9a6c67e4-d666-54a8-9465-4847bee812e2"
svtrid: "aafce8b5-2a77-4d97-9095-1b2475da2eaf"
time: 0.0079150199890137
}

Notification message types

There is totally 10 events which will generate message in a queue:

Domain expired. Message type “DOMAIN_EXPIRE”.
Domain entered redemption period. Message type “DOMAIN_REDEMPTION”.
Domain deleted. Message type “DOMAIN_DELETE”.
Insufficient funds to complete operation. Message type “INSUFFICIENT_FUNDS”.
Balance low. Message type “BALANCE_LOW”.
Automatic invoice created by ST Registry. Message type “AUTO_INVOICE”.
Unpaid invoice reminder. Message type “UNPAID_INVOICES”.
Transfer request. Message type “TRANSFER_REQUEST”.
Transfer successful. Message type “TRANSFER_SUCCESS”.
Transfer rejected. Message Type “TRANSFER_REJECT”.
Transfer cancelled. Message type “TRANSFER_CANCEL”.
Transfer forbidden. Message type “TRANSFER_FORBIDDEN”.