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.

1. Read messages queue

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:

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

Request method: GET

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.

Request example:

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

Response example:

 

2. Acknowledge Message

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.

URI: /notifications/:id:/read
Request method: POST

Name	Description
id	Message identifier for acknowledgement.

Request example:

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.

Response example:

 

3. Notification message types

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

1. Domain expired. Message type “DOMAIN_EXPIRE”.
2. Domain entered redemption period. Message type “DOMAIN_REDEMPTION”.
3. Domain deleted. Message type “DOMAIN_DELETE”.
4. Insufficient funds to complete operation. Message type “INSUFFICIENT_FUNDS”.
5. Balance low. Message type “BALANCE_LOW”.
6. Automatic invoice created by ST Registry. Message type “AUTO_INVOICE”.
7. Unpaid invoice reminder. Message type “UNPAID_INVOICES”.
8. Transfer request. Message type “TRANSFER_REQUEST”.
9. Transfer successful. Message type “TRANSFER_SUCCESS”.
10. Transfer rejected. Message Type “TRANSFER_REJECT”.
11. Transfer cancelled. Message type “TRANSFER_CANCEL”.
12. Transfer forbidden. Message type “TRANSFER_FORBIDDEN”.

 

3.1. Domain expired

This message is generated when domain gain status serverHold when it reach expire date.

 

Example of REST API response for this message type:

 

 

3.2. Domain entered redemption period

This message is generated when domain gain status redemptionPeriod which occurs 40 days after expire event occurred.

 

Example of REST API response for this message type:

 

 

3.3. Domain deleted

This message is generated when domain completely removed from ST Registry repository and became publicly available for registration.

 

Example of REST API response for this message type:

 

 

3.4. Insufficient funds

Message “Insufficient funds to complete operation” is generated if any operation which generate billing transaction was not completed due to the billing exception (insufficient funds on registrar balance to complete operation).

 

Example of REST API response for this message type:

 

 

3.5. Balance low

This warning message is generated by ST Registry if registrar balance is below defined limit. Balance limit is calculated on monthly basis and calculate total number of funds needed to renew domains within next 3 months + number of domains registered during past 3 months. Resulting balance limit should cover hypothetic possible operations during next 3 months. Balance is compared with limit on a daily basis and if its goes below defined limit – corresponding message is generated by ST Registry.

 

Example of REST API response for this message type:

 

 

3.6. Automatic invoice

This message is generated when ST Registry create automatic invoice basing on current registrar balance and balance limit calculated in message “3.5 Balance low“.

Example of REST API response for this message type:

 

 

3.7. Unpaid invoice

This message is generated as a reminder for unpaid invoice(s).

Example of REST API response for this message type:

 

 

3.8. Transfer request

This message is generated for the loosing ST Registrar when a transfer request is issued for any domain. Transfer status in this case gain “pending” value.

 

Example of REST API response for this message type:

 

 

3.9. Transfer successful

This message is generated for the gaining ST Registrar when a transfer request for a domain was accepted by loosing ST Registrar or if transfer request was automatically approved by ST Registry (in case of inactivity by loosing ST Registrar for 7 days).

“paResult” attribute gain a positive Boolean value which indicate that request has been approved and completed. Transfer status in this case gain “clientApproved” value.

 

Example of REST API response for this message type:

 

 

3.10. Transfer rejected

This message is generated for gaining/requesting ST Registrar when a transfer request for a domain was rejected by loosing ST Registrar.

“paResult” attribute gain a negative Boolean value which indicate that request has been rejected. Transfer status in this case gain “clientRejected” value.

 

Example of REST API response for this message type:

 

 

3.11. Transfer cancelled

This message is generated for the loosing ST Registrar when a transfer request was initiated but cancelled by gaining/requesting ST Registrar before transfer was completed.

“paResult” attribute gain a negative Boolean value which indicate that request has been cancelled. Transfer status in this case gain “clientCancelled” valued.

 

Example of REST API response for this message type:

 

 

3.12. Transfer forbidden

This message is generated for the gaining/requesting ST Registrar when the registry reject a transfer request for a domain. This might occur when domain status forbid transfer operation.

“paResult” attribute gain a negative Boolean value which indicate that request has been rejected. Transfer status in this case gain “serverRejected” value.

 

Example of REST API response for this message type: