Class ServerApi

Description

Function documentation

This document lists all the functions (methods) that can be called via ISNIC's SOAP API interface.

Production server
The WSDL is located at https://api.isnic.is/1.0/index.php?soap=ServerApi.wsdl

Developement server
There is also a test interface that can be used for developement. All functions are availabe just like in the production system.
It has the following limitations:

  • Domains created won't be created in the .is zone.
  • Payments are only possible with special test card numbers

The WSDL for the developement server is located at https://api-dev.isnic.is/1.0/index.php?soap=ServerApi.wsdl

Developement creditcard number:
VISA, 4571999400007492, CVC 150, (exp. date any date in the future)
This card is of course only usable on ISNIC's developement API server.

Return values

Since functions need to return multiple things, they all return a object instance (instead of a primative type). Ideally they all should return a object of the same type to make things more simple.

This is however not possible, since some functions need to return a different type of data. Even though there is a common variable '$value' in all the objects returned, and used for function specific data, we need to specify it's type. The type of $value for the function infoContact() would be IsnicContact but for infoDomain() the would be IsnicDomain

Whenever possible, the function's return value is of type IsnicApiResult

The IsnicApiResult contains the following variables:
$msg
A human readable message

$processReferenceID
A unique Reference ID for asynchronous functions (see below)

$resultCode
The type of success or failure as a result of this function call.
See the constants in IsnicApiConstants for possibles values.

$value
The data returned by the function. Note that many functions don't need to return any data (the $resultCode indicates success or failure)

In some cases a function need to return a different type than IsnicApiResult. Those different return types still have the variables mentioned above, but usually the $value variable is of a different type.

For example, infoHost() returns a object of type IsnicInfoHostResult, which is identical to IsnicApiResult except $value is of type IsnicHost instead of 'string'.

Synchronous/Asynchronous functions

Please note that the term synchronous does not refer to the usual 'program waits until the previous instance has finished' definition.

Synchronous function returns with a $resultCode that is final and the function has completed what it was asked to do.

Asynchronous function returns with a $resultCode of SUCCESS_PENDING (if successful), but the processing hasn't finished. The variable $processReferenceID in the returned object is set to a unique ID for future reference.
A message will be sent (and received via pollMessages() indicating final success or failure of the command, and the $processReferenceID of the message will match the one returned by the function.

Functions are marked either synchronous/asynchronous in the documentation for each function.

  • author: olafure@isnic.is
  • author: snorri@isnic.is

Located in /Api/Server/ServerApi.php (line 132)

CWebServiceAction
   |
   --ServerApi
Class Constant Summary
 VERSION = "1.0"
Method Summary
 ServerApi __construct ([ $controller = null], [ $id = null], [ $config = []])
 IsnicApiResult addDsRecord (string $domainName, IsnicDsRecord $dsRecord)
 IsnicApiResult checkContact (string $handle)
 IsnicApiResult checkDomain (string $domainName, [string[] $hostnames = null])
 IsnicApiResult checkHost (string $hostname, [string[] $addresses = null])
 IsnicApiResult createDomain (IsnicDomain $domain, integer $creditcardID, integer $creditcardCVC)
 IsnicApiResult createHost (string $hostname, string[] $addresses, string $adminContactHandle)
 IsnicApiResult deleteDomain (string $domainName)
 IsnicApiResult deleteHost (string $hostname)
 string echoInput (string $input)
 string getOwner ()
 string getVersion ()
 IsnicInfoContactResult infoContact (string $contactHandle)
 IsnicInfoDomainResult infoDomain (string $domainName)
 IsnicInfoHostResult infoHost (string $hostname)
 string invoicePdf (string $invoiceID, [bool $showBackground = true])
 IsnicListCreditTransactionsResult listCreditTransactions (integer $creditID, [date $fromDate = null], [date $toDate = null])
 IsnicApiResult login (string $username, string $password)
 IsnicApiResult removeDsRecord (string $domainName, IsnicDsRecord $dsRecord)
 IsnicApiResult renewDomain (string $domainName, integer $creditcardID, integer $creditcardCVC)
 IsnicApiResult renewDomains (string[] $domainNames, integer $creditcardID, integer $creditcardCVC)
 IsnicApiResult transferRegistrant (string $domainName, IsnicRegistrant $newRegistrant)
 IsnicApiResult updateContact (string $contactHandle, string $contactPassword, IsnicContact $updatedContact)
 IsnicApiResult updateDomain (string $domainName, IsnicDomain $updatedDomain)
 IsnicApiResult updateDomainNameserver (string $domainName, string[] $hostnames)
 IsnicApiResult updateHost (string $hostname, IsnicHost $updatedHost)
 IsnicApiResult verifyContact (string $handle, string $hash)
Methods
Constructor __construct (line 160)
ServerApi __construct ([ $controller = null], [ $id = null], [ $config = []])
  • $controller
  • $id
  • $config
addDsRecord (line 840)

Adds a DS record

Synchronous

Adds a DS record.

  • access: public
IsnicApiResult addDsRecord (string $domainName, IsnicDsRecord $dsRecord)
checkContact (line 305)

Indicates if the given contact has been confirmed or not.

Synchronous

Return value's $value field is set to '1' if confirmed, 0 otherwise.

All newly created contacts have to be confirmed. ISNIC's system will send the contact a e-mail that he has to confirm (by clicking a link in the e-mail).

  • access: public
IsnicApiResult checkContact (string $handle)
  • string $handle: contact handle. See the handle property of the IsnicContact class.
checkDomain (line 522)

Check domain for existance and validity OR check if domain is correctly set up on nameservers.

Synchronous

If just the $domainName parameter is given ($hostnames parameter set to null), then an existance check is performed on the domain. The domain is also checked to be valid.

Return value's $value variable is "1" if domain exists, "-1" if it has been queued for creation, "-2" if the domain is invalid, otherwise "0".

If the $hostname array is given, a test is done on the specified nameservers to see if they fullfill ISNIC's nameserver requirements for that domain.
If the test fails, $msg variable will describe what failed.
Return value's $value variable is "1" if test passes, otherwise "0".

  • access: public
IsnicApiResult checkDomain (string $domainName, [string[] $hostnames = null])
  • string $domainName: ascii version of the domain name to check for.
  • string[] $hostnames: array of strings, each item is a fully qualified hostname for a nameserver that has a zone for the domain $domainName. At least 2 nameservers must be specified and maximum of 4.
checkHost (line 549)

Checks if host is registered with ISNIC or perform a test on host.

Synchronous

If $addresses parameter is null, only an existance check is made. Return's $value variable is "1" if host is registered, othewise "0".

If \$addresses are set then a nameserver test is performed on $hostname.
Nameservers must pass this test to be able to host .is domains.
Return value's $value variable is "1" if test passes, otherwise "0".
If the test fails, $msg variable will describe what failed.

In both cases the $resultCode is SUCCESS_DONE.

  • access: public
IsnicApiResult checkHost (string $hostname, [string[] $addresses = null])
  • string $hostname: fully qualified hostname for the nameserver.
  • string[] $addresses: array of addresses for the nameserver (if to perform the test)
createContact (line 287)

Creates a new contact.

Synchronous

Note that contact is not usable until he has been confirmed.
ISNIC mail system will send e-mail to contact's email address and ask them to click on a link in it. After the contact has done that, the contact is confirmed.

The newly created contact handle is returned int the $value variable.

See checkContact() for checking if the contact has been confirmed.

  • access: public
IsnicApiResult createContact (IsnicContact $isnicContact)
createDomain (line 263)

Create a new .is domain.

Aynchronous

When registering a new domain, the following variables have to be set in the $domain object parameter:
domainNameIdn, registrant, adminContact, techContact, billingContact, nameserver1, nameserver2, isParked.

  • access: public
IsnicApiResult createDomain (IsnicDomain $domain, integer $creditcardID, integer $creditcardCVC)
  • IsnicDomain $domain: object describing the domain being registered
  • integer $creditcardID: ID of the creditcard to be billed for the domain.
  • integer $creditcardCVC: the CVC number on the back of the card
createHost (line 653)

Register a new nameserver to use with .is domains.

Synchronous

Nameservers have to be registered with ISNIC before they can be used to host .is domains.

  • access: public
IsnicApiResult createHost (string $hostname, string[] $addresses, string $adminContactHandle)
  • string $hostname: fully qualified hostname for the host to create
  • string[] $addresses: array of ip addresses for the host. Only required for .is hostnames.
  • string $adminContactHandle: the handle of a contact that will be the domain's admin contact.
createPrepaidCard (line 823)

Creates a new prepaid creditcard object.

Synchronous

The ID of the new prepaid card is returned in the $value variable.
This creditcard ID is used to refer to the creditcard when registering a new domain or paying for other items.

  • access: public
IsnicApiResult createPrepaidCard ()
deleteDomain (line 761)

Request a deletion of a .is domain.

Asynchronous

Current user must be the domain's admin contact to request deletion.

The domain's admin contact will need to confirm the deletion via automatic confirmation e-mail.

  • access: public
IsnicApiResult deleteDomain (string $domainName)
  • string $domainName: ascii version of the domain name to delete.
deleteHost (line 780)

Request a deletion of a host object.

Synchronous

Current user must be the host's contact. An e-mail is sent to the host'a admin contact to notify him of the deletion.

The host can not currently be in use as a nameserver for a .is domain.

  • access: public
IsnicApiResult deleteHost (string $hostname)
  • string $hostname: fully qualified name of host to request deletion for
echoInput (line 383)

Echos back your input string. Max 256 bytes returned. Usable for testing correct encoding.

Synchronous

  • access: public
string echoInput (string $input)
  • string $input
getOwner (line 370)

Returns the owner of the API server.

Synchronous

Owner is always same

  • access: public
string getOwner ()
getVersion (line 356)

Returns the version of the API server.

Synchronous

Version has the format [major].[minor], For example, "1.1".

Version 1.9 is older than version 1.10.

  • access: public
string getVersion ()
infoContact (line 573)

Returns information about a contact.

Synchronous

Contact information is returned in the $value variable which is a instance of IsnicContact.

Contact's password is set to an empty string.

Note that this function is rate limited at 15 requests per hour.
If rate limit is exceeded, $resultCode variable is set to ERROR_SESSION_LIMIT_EXCEEDED

  • access: public
IsnicInfoContactResult infoContact (string $contactHandle)
  • string $contactHandle: handle of the contact to look for
infoDomain (line 617)

Returns information about a domain.

Synchronous

If domain exists, domain information is returned in the $value variable, which is a instance of IsnicDomain. Otherwise $value is null.

Note that this function is rate limited at 15 requests per hour.
If rate limit is exceeded, $resultCode variable is set to ERROR_SESSION_LIMIT_EXCEEDED. Rate limit does not apply to domains which the currently logged in user has access to.

  • access: public
IsnicInfoDomainResult infoDomain (string $domainName)
  • string $domainName: ascii version of the domain name to lookup
infoHost (line 594)

Returns information about a host registered with ISNIC.

Syncronous

Host information is returned in $value variable, which is a instance if InsnicHost

Note that this function is rate limited at 15 requests per hour.
If rate limit is exceeded, $resultCode variable is set to ERROR_SESSION_LIMIT_EXCEEDED

  • access: public
IsnicInfoHostResult infoHost (string $hostname)
  • string $hostname: fully qualified hostname of the nameserver to return info for.
invoicePdf (line 397)

Returns pdf invoice.

Synchronous

  • access: public
string invoicePdf (string $invoiceID, [bool $showBackground = true])
  • string $invoiceID
  • bool $showBackground: (optional)
listCreditcards (line 322)

Returns a array of creditcards belonging to the currently logged in user.

Synchronous

Return value's $value property is an array of IsnicCreditcard objects.
Please note that the card's cvc number is not stored in ISNIC's database so it's not included in the list.

IsnicListCreditcardsResult listCreditcards ()
listCreditTransactions (line 340)

Returns a array of transactions belonging the selected credit.

Synchronous

Return value's $value property is an array of IsnicCreditTransaction objects.

IsnicListCreditTransactionsResult listCreditTransactions (integer $creditID, [date $fromDate = null], [date $toDate = null])
  • integer $creditID
  • date $fromDate: (optional) yyyy-mm-dd
  • date $toDate: (optional) yyyy-mm-dd
listDomains (line 471)

Returns a list of domains.

Synchronous

The list includes all domains that the currently logged in user is any type of contact for.

The domains are returned in the $value variable, which is an array of IsnicDomain instances.

  • access: public
IsnicListDomainsResult listDomains ()
login (line 243)

Authenticate the user.

Synchronous

All functions will return ERROR_AUTHENTICATION as $resultCode until the user has successfully logged on.

After login pass in the value from the value variable got from the login into the http get variable named session.

Please note that only usernames with special attributes set by ISNIC can use the API interface.

Note that this function is rate limited at 20 requests per 10 min.
If rate limit is exceeded, $resultCode variable is set to ERROR_SESSION_LIMIT_EXCEEDED

  • access: public
IsnicApiResult login (string $username, string $password)
  • string $username: NIC handle for the user
  • string $password: plaintext password
logout (line 806)

Logs out the currently logged in user.

  • access: public
IsnicApiResult logout ()
pollMessages (line 418)

Returns messages that indicate result code of pending asynchronous functions.

Synchronous

The messages are returned in the $value variable, which is an array of IsnicApiMessage objects.

Each IsnicApiMessage has a $processReferenceID variable that links it with the specific function call.
The message also has an $resultCode which indicates the success/failure of the function call.

  • access: public
IsnicPollMessagesResult pollMessages ()
removeDsRecord (line 877)

Removes a DS record

Synchronous

Removes a DS record.

  • access: public
IsnicApiResult removeDsRecord (string $domainName, IsnicDsRecord $dsRecord)
renewDomain (line 435)

Renew a domain.

Domain's expire date is increased by a year.

Synchronous

  • access: public
IsnicApiResult renewDomain (string $domainName, integer $creditcardID, integer $creditcardCVC)
  • string $domainName: ascii version of the domain names to renew, with the .is suffix.
  • integer $creditcardID: ID of the creditcard to be charged.
  • integer $creditcardCVC: CVC number from the back of the card.
renewDomains (line 452)

Renew domains.

Domain's expire dates are increased by a year.

Synchronous

  • access: public
IsnicApiResult renewDomains (string[] $domainNames, integer $creditcardID, integer $creditcardCVC)
  • string[] $domainNames: ascii version of the domain names to renew, with the .is suffix.
  • integer $creditcardID: ID of the creditcard to be charged.
  • integer $creditcardCVC: CVC number from the back of the card.
transferRegistrant (line 796)

Request the transfer of the domain to new registrant.

Asynchronous>

Current user must be domain's admin contact.

  • access: public
IsnicApiResult transferRegistrant (string $domainName, IsnicRegistrant $newRegistrant)
  • string $domainName: ascii version of the domain name.
  • IsnicRegistrant $newRegistrant: information about the new registrant.
updateContact (line 721)

Update contact information.

Syncronous.

Not that it's not possible to change contact's handle.

Contact's password must be supplied in the $contactPassword parameter.

The password in $updatedContact should be empty string if it is not to be changed.

Note that this function is rate limited at 50 requests per half hour.
If rate limit is exceeded, $resultCode variable is set to ERROR_SESSION_LIMIT_EXCEEDED

  • access: public
IsnicApiResult updateContact (string $contactHandle, string $contactPassword, IsnicContact $updatedContact)
  • string $contactHandle: handle of the contact to update
  • string $contactPassword: plaintext password for the contact to update
  • IsnicContact $updatedContact: how the contact should look like after the change.
updateDomain (line 672)

Update domain information.

Synchronous.

Currently logged in user must be admin contact for the domain that is to be modified.

The domain $domainName will be updated, with information found in $updatedDomain.

  • access: public
IsnicApiResult updateDomain (string $domainName, IsnicDomain $updatedDomain)
  • string $domainName: ascii version of the domain name that is to be updated
  • IsnicDomain $updatedDomain: how the object should look like after the update.
updateDomainNameserver (line 693)

Update the nameserver for a domain.

Asynchronous.

Logged in user must be admin contact for the domain being modified.

  • access: public
IsnicApiResult updateDomainNameserver (string $domainName, string[] $hostnames)
  • string $domainName
  • string[] $hostnames: array of fully qualified hostnames, which will be set as the domain's nameservers. At least 2 nameservers are required and a maximum of 4 can be set. Nameservers must be registered with ISNIC before, see ServerApi::createHost()
updateHost (line 743)

Update host information.

Asynchronous.

Current user must be the host's admin contact. Therefore if you change you admin contact, you won't be able to edit it again.

  • access: public
IsnicApiResult updateHost (string $hostname, IsnicHost $updatedHost)
  • string $hostname: fully qualified hostname to change.
  • IsnicHost $updatedHost: how the host should look like after the update.
verifyContact (line 635)

Verifies contact so it's useable to register domain.

Return value's $value is '1' on successful verifitcation, otherwise '0'.

$resultCode is SUCCESS_DONE.

On error, more detailed error message is in $msg.

  • access: public
IsnicApiResult verifyContact (string $handle, string $hash)
  • string $handle: contact's handle
  • string $hash: verification hash sent in e-mail.
Class Constants
VERSION = "1.0" (line 134)

Documentation generated on Wed, 11 Nov 2015 11:35:24 +0000 by phpDocumentor 1.4.4