Collections

Contents

ST Registry has implemented collections to improove communication performance between Registrar and ST Registry.

For collections was created unified list of parameters to manage filtration, sortings etc.

Name Description
field Filter data represented as array.

Array format:

field[{field_name}][{compare_function}]={value}

where

field_name – field name where should be applied filter. You can find field names in JSON representation for each object.

compare_function – comparsion function for filter:

  • eq – equal to value.
  • not – not equal to value.
  • like – simple pattern matching. Verify that provided value is a part of field_name value.
  • nlike – opposite to like. Verify that provided value is NOT a part of field_name value.
  • lt – less then value.
  • gt – greater than value.
  • lte – less or equal to value.
  • gte – greated or equal to value.

value – filter value. If value is array – it will be transformed into construction IN/NOT IN according to selected comparsion function. All date values are accepted in both formats: timestamp and datetime string (yyyy-mm-dd format)

Filters can be combined in any order.

For one field can be provided several filters.

op Logical operation to unite filters.

Operation can gain value:

  • and
  • or

if nothing is provided – by default is used operator and.

limit Result limit in response. In other words – number of objects to fetch starting from “offset” position.
offset Identify how many objects should be skipped before starting fetching objects.
sort_field Identify object attribute which should be used for sorting results.
sort_direction Sorting direction. May acquire values: asc or desc (ascending or descending).

Every response to collection request will include information:

  • searchInf/limit – requested result limits
  • searchInf/offset – requested result offset
  • searchInf/rows_count – total rows count according to applied filter values.

 

Example for IN construction:

URI: /collection_name/?do=search&field[‘field_name’][‘eq’][]=’ABC1’&field[‘field_name’][‘eq’][]=’ABC2′

This request will search for objects where field_name value exist in array [‘ABC1′,’ABC2’].

 

Example for OR logical operation:

URI: /collection_name/?do=search&field[‘field_name1’][‘eq’]=’ABC1’&field[‘field_name2’][‘eq’]=’ABC2’&op=or

This request will return all results where field_name1=ABC1 OR field_name2=ABC2.

Domains collection

URI: /domains/?do=search
Request method: GET

Request example:

After successful authentication request, response will contact searchRes – collection of domains:

  • name – Request domain name. Value always available in response.
  • clID – ClientID who is currently acting registrar for the domain. In other words this is a client/registrar ID who is making this request. Value always available in response.
  • crID – ClientID who has originally registered/created this domain. Value always available in response.
  • crDate – Domain registration date. Value always available in response.
  • upDate – Date for the last successful update command execution. This value is optional and may not be available in response if domain didn’t got any successful update commands after domain registration/creation.
  • exDate – Domain expire date. Value always available in response.
  • ns – Name servers collection assigned to the current domain. This collection is optional and may not be available in response if domain have no assigned name servers.
  • contacts – Contacts collection assigned to the current domain. There is totally 4 kind of contacts: registrant, admin, billing, tech. All of them are required and always available in response. Collection may also contain optional values which are represented if assigned to the domain: registrant_privacy, admin_privacy, billing_privacy, tech_privacy. Read more about privacy in paragraph “WHOIS Privacy“.
  • status – Collection of status codes. More details on status codes page. Domain always have at least 1 status which mean that this collection is always available in response.
  • statusDate – Collection of all status codes from “status” collection but with date when each status code was assigned to current domain.
  • authInfo – Contain attribute pw – which identify AuthCode/EPPCode for domain. AuthCode/EPPCode is required to gain control over domain by other client/registrar or registrant. Usually is used to initiate domain transfer between clients/registrars.
  • 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:

It is possible to perform search by any field from result domain object field set.

Example for searching all domains with any contact value ‘ABC-12345’:

URI: /domains/?do=search&field[‘contact’][‘eq’]=’TEM525418792851B’

Contacts collection

URI: /contacts/?do=search

Request method: GET

Request example:

After successful authentication request, response will contact searchRes – collection of domains:

  • id – unique identifier for the contact.
  • postalInfo – may contain one or two elements with address information – “int” and/or “loc”.
    type=”int” – text only in Latin.
    type=”loc” – text on national language in UTF-8.
    postalInfo include following subelements:

    • name – name.
    • org – organisation.
    • addr – address, contain of subelements:
      • street – up to 3 string.
      • city – city.
      • sp – province.
      • pc – postal code.
      • cc – country code according to the ISO 3166.
  • voice – telephone number. Contact telephone number structure is derived from structures defined in [ITU.E164.2005].  Telephone numbers described in this mapping are character strings that MUST begin with a plus sign (“+”, ASCII value 0x002B), followed by a country code defined in [ITU.E164.2005], followed by a dot (“.”, ASCII value 0x002E), followed by a sequence of digits representing the telephone number.  An optional “x” attribute is provided to note telephone extension information.
  • fax – fax number. Fax number format requirements are identical to the <contact:voice>.
  • email – email address.
  • authInfo/pw – AuthInfo (also known as AuthCode or EPPCode).

Response example:

Hosts collection

URI: /hosts/?do=search

Request method: GET

Request example:

After successful authentication request, response will contact searchRes – collection of domains:

  • name – host name queried in this request.
  • clID – ClientID – current host sponsor.
  • crID – ClientID – host creator.
  • crDate – date when host was created.
  • addr – elements that contain collection of IP addresses associated with current host which is represented in pairs key->value.
    • Key may obtain value “v4” or “v6” which identify IP version.
    • Value should represent IP in version that is identified by Key.
  • 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:

 

Billing transactions collection

URI: /billing/?do=search

Request method: GET

Request example:

After successful authentication request, response will contact searchRes – collection of domains:

  • TransactionUUID – Unique identifier for transaction.
  • clID – ClientID where transaction is related. Normally this is ID of requesting client.
  • BillingRecordName – Predefined by registry operation name.
  • Period – Operation period. OPTIONAL, available only for registration and/or renewal operation. Value reflect period in months.
  • Amount – Total amount/price for billing operation in currency defined by field “Currency”.
  • Status – Transaction payment status. May obtain values: PAID or NOT_PAID. When credit limit is used to create transaction – such transaction will gain status NOT_PAID until registrar/client will pay invoice which include unpaid transactions.
  • Currency – Currency which was used in corresponding transaction.
  • Description – Transaction description which was generated by ST Registry.
  • DateCreated – Date and time when transaction was created.
  • DatePaid – Date and time when transaction was paid using client balance or invoice (in case of credit limit usage).
  • DomainName – Optional, reference to domain name for current transaction
  • InvoiceUUID – Optional, Invoice number which was used to mark as “PAID” current transaction. Value is defined only for transactions that was paid and previously created using client credit limit.

Response example:

Invoices collection

URI: /invoices/?do=search
Request method: GET

Request example:

After successful authentication request, response will contact searchRes – collection of domains:

  • number- Unique invoice number.
  • dateIssue – Date and time when invoice was issued.
  • dateDue – Due date for invoice.
  • datePaid – Date and time when invoice was paid.
  • Status – Invoice payment status. May obtain values: PAID or NOT_PAID.
  • currency- Invoice currency.
  • Currency – Currency which was used in corresponding transaction.
  • issuerName, issuerAddr, issuerCity, issuerCountry, issuerBillingEmail, issuerPostalCode, issuerFax, issuerVatId – Issuer details in the moment when invoice was issued (ST Registry details).
  • clientName, clientAddr, clientCity, clientCountry, clientBillingEmail, clientPostalCode, clientFax, clientVatId – client details in the moment when invoice was issued.
  • VAT- client VAT rate.
  • TotalNet – Invoice total NET worth price. Amount before VAT is added.
  • TotalGross – Invoice total GROSS worth price. Amount after VAT is added
  • clID – Client ID where invoice is related. Normally this is a same client who is requesting this result.r
  • records – Collection of invoice records.
  • notes – Collection of invoice notes. Usually this is remarks about payment or comments from registry or just communication about invoice between ST Registry and the Client.

Response example:

 

dotster