Domain Management API. Revision V1.1

Transcription

1 Domain Management API Revision V1.1 August 2012

2 Introduction This API document contains all the information that a software developer will need to create a program that will be able to manage services with Daily.co.uk. The API covers the following actions: Register a Look up a 's availability Retrieve specific details about s already in your account Renew your s Transfer s into your account Manage the name servers for all of your s Full DNS management for all of your s Manage the contact details attached to your s Look up the amount of credits in your account Each registration or renewal will cost the account holder one credit per year of renewal or registration. How does it work? The Daily API requires you to use your account username and password to login. When you have called the login with your account credentials you will be given a Token (a less than 200 character pass phrase) which you will need to supply with every action you make. The Token will be valid until 5 minutes of inactivity has occurred. The API uses a HTTP POST that contains information about which you'd like to access and the additional values that this requires. For example return whether the microsoft.com is available for registration or not. The returned data can be viewed in several formats such as KVP (Key Value Pairs), XML (extendible Markup Language) or JSON (JavaScript Object Notation). KVP Example: =daily.co.uk =taken XML Example: <response> <>daily.co.uk</> <>taken</> </response> JSON: { } : daily.co.uk, : taken, To select the language in which you receive the response you will need to alter the URL that you post the HTTP request to. Response Language KVP XML JSON URL

3 How to pay for Domain Registrations, Transfers and Renewals Some of the services that are available through this API require a payment. Payments are made using Domain Credits at the rate of 1 credit per year of registration or renewal and 1 credit per transfer (excluding CentralNic and Nominet transfers which are free of charge). Domain credits can be purchased from vary in price depending on the quantity ordered. Standard Error Responses If an API call you make fails due to an error with the Daily API or because the values submitted were invalid you will be shown a standard error response: KVP: =error error=this request failed because... XML: <response> <>error</> <error>this request failed because...</error> </response> JSON: { } : error, error : This request failed because..., If you feel that the error message you are shown is not descriptive enough to enable you to debug the problem, please contact the Daily helpdesk so that additional text can be added to the response. API Access Rate Limits To ensure the availability of the API service to all customers there are two minor restrictions imposed on the API users (all restrictions are on a rolling period, so if you are limited it will only be for a short time). 1. A limit of 3600 per hour is applied to all connections. If more than 1 per second is made you will be restricted until the balance is restored. 2. A limit of 60 requests within a 5 minute period is applied to just external connection (such as lookups and WHOIS calls). This limit is imposed until the balance is restored. If you are limited you will receive an error response, e.g.: =error error=access limit exceeded.

4 Contents 1. Login Management 1. Get login Login function 2. Check Check login 3. Clear Logout function 2. Account Status 1. Credit check Check account credits (used for payments) 2. Order check Check the of order items 3. Domain renewals Get list of due for renewal 3. Contacts Management 1. Contacts list List all contacts in your account (used for registrations and transfers) 2. Create contact Add a contact to your account 3. Delete contact Delete a contact from your account 4. Domain Management 1. Domain list List all the s in your account 2. Domain lookup Check a s availability 3. Domain register Register a for your customer using credits as payment 4. Domain transfer Transfer a to your account at Daily using credits as payment 5. Domain renew Renew one of your s that has a renewal due 5. DNS Management 1. Get DNS records Fetch all DNS records for a in your account 2. Create a DNS record Create a DNS record for a in your account 3. Delete a DNS record Remove a DNS record for a in your account. 4. Reset ZONE Reset the zone file to the Daily defaults.

5 Login Management Get Login Token In order to access the API you must have a valid, you can get a by calling this with your Daily username and API password that can be enabled through your Daily Control Panel in the My Account section. Method _get Username Password Your Daily username that you use to access This is your API password that you can enable through the Daily control panel in the My Account section. Status last_access Token Ok :00:00 This is the timestamp of when you logged in to the API. This is the password that you will need for all other API calls Example =_get; username=my_username; password=mypassword =ok last_access= :00:00 =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx Check Token If at any point during your session you'd like to lookup the details about your you can use this. _check pass phrase that supplied by the _get last_access Ok :00:00 This is the timestamp of when you last accessed the API to perform an action. Example =_check; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; =ok last_access= :00:00

6 Clear Token (logout) After you have performed the action(s) that you wish to make during this session it is advised that you logout your using this. _clear pass phrase that supplied by the _get Ok Example =_clear; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; =ok

7 Account Status Credit Check This reports the number of credits that you have available for.com,.net,.org,.info,.biz,.cc,.tv and.uk registrations, renewals and transfers. credits_check pass phrase that supplied by the _get uk cnoib 999 number of credits that can be used for.uk registrations, renewals and transfers (one credit per year). 999 number of credits that can be used for.com,.net,.org,.info and.biz s. Example =credits_check; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; uk=999 cnoib=999 Order Check This requires an order_id and returns the of this order, failed or filled. order_id order_ order_id order_items.n. order_items.n.name order_items.n.product_code order_items.n.id Example order_check pass phrase that supplied by the _get an order an that belongs to your account. filled, failed, filling the order id that you requested. Filled, failed or filling the of each item in the order. Product name for each of the items in the order Daily product code for each of the items in the order. Id for each of the items in the order. =order_check; order_id=12345 =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; order_=filled order_id=12345 order_items.0.stauts=filled order_items.0.name=register example.co.uk for 2 years (Domain Credit) order_items.0.id=54321

8 Domain Renewals This optionally requires number of days (default 60) to fetch a list of s that will be expiring within the next X amount of days. _renewals pass phrase that supplied by the _get Days Number of days from now (ie 30) s.n. s.n. s.n.created s.n.expires Example Live, suspended or closed. The name that requires a renewal. YYYY-MM-DD HH:MM:SS created timestamp YYYY-MM-DD HH:MM:SS expires timestamp =_renewals; days=30; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; s.0.created= :00:00 s.0.=example.co.uk s.0.expires= :00:00 s.1.created= :00:00 s.1.=example.com s.1.expires= :00:00 s.2.created= :00:00 s.2.=exmaple.uk.com s.2.expires= :00:00

9 Contacts Management List all Contacts This will retrieve a list of all your contacts which are used for registration and contact details update. contacts_list pass phrase that supplied by the _get contacts.n.id contacts.n.forename contacts.n.surname contacts.n. contacts.n.address1 contacts.n.address2 contacts.n.town contacts.n.region 999 this is the id of the contact's record. Letters, spaces and -'s are allowed. Letters, spaces and -'s are allowed. A valid address. Alphanumeric string. Alphanumeric string. Alphanumeric string. If the country is United States then this should be the escaped 2 character region code. contacts.n.country contacts.n.postcode contacts.n.phone contacts.n.fax contacts.n.organisation contacts.n.usertype CODE User Type: If the country is United Kingdom then this value should be the county. This must be the the ISO alpha-code country name. For reference please view: Alphanumeric string. Telephone number format is +[COUNTRY CODE].[PHONE NUMBER]x[EXT (optional)], for example: Telephone number format is +[COUNTRY CODE].[PHONE NUMBER]x[EXT (optional)], for example: Only applicable to businesses. LTD PLC PTNR STRA LLP IP IND SCH RCHAR GOV CRC STAT OTHER FIND FCORP FOTHER UK Limited Company UK Public Limited Company UK Partnership UK Sole Trader UK Limited Liability Partnership UK Industrial/Provident Registered Company UK Individual (representing self) UK School UK Registered Charity UK Government Body UK Corporation by Royal Charter UK Statutory Body UK Entity that does not fit into any of the above (e.g. clubs, associations, many universities) Non-UK Individual (representing self) Non-UK Corporation Non-UK Entity that does not fit into any of the above (e.g. charities, schools, clubs, associations) contacts.n.company_number Example Only applicable to businesses. =contacts_list; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; contacts.0.id=1 contacts.0.forename=my contacts.0.surname=name contacts.0.organisation=my Company contacts.0. =me@me.com contacts.0.address1=my Address

10 contacts.0.address2= contacts.0.town=my Town contacts.0.region=london contacts.0.country=united Kingdom contacts.0.postcode=aa1 11AA contacts.0.phone= contacts.0.fax= contacts.0.usertype=ind contacts.0.company_number= contacts.1.id=2 contacts.1.forename=your contacts.1.surname=name contacts.1.organisation=your Company contacts.1.address1=you Address contacts.1.address2= contacts.1.town=your Town contacts.1.region=derbyshire contacts.1.country=united Kingdom contacts.1.postcode=aa1 11AA contacts.1.phone= contacts.1.fax= contacts.1.usertype=ind contacts.1.company_number= Create A Contact This will you to create a new contact record that can be used for registrations or transfers. forename surname address1 address2 town region country contacts_create pass phrase that supplied by the _get Letters, spaces and -'s are allowed. Letters, spaces and -'s are allowed. A valid address. Alphanumeric string. Alphanumeric string. Alphanumeric string. If the country is United States then this should be the escaped 2 character region code. If the country is United Kingdom then this value should be the county. This must be the the ISO alpha-code country name. For reference please view: postcode phone fax organisation usertype Alphanumeric string. Telephone number format is +[COUNTRY CODE].[PHONE NUMBER]x[EXT (optional)], for example: Telephone number format is +[COUNTRY CODE].[PHONE NUMBER]x[EXT (optional)], for example: Only applicable to businesses. Code User Type LTD PLC PTNR STRA LLP IP IND SCH RCHAR GOV CRC STAT OTHER UK Limited Company UK Public Limited Company UK Partnership UK Sole Trader UK Limited Liability Partnership UK Industrial/Provident Registered Company UK Individual (representing self) UK School UK Registered Charity UK Government Body UK Corporation by Royal Charter UK Statutory Body UK Entity that does not fit into any of the above (e.g. clubs, associations, many

11 company_number FIND FCORP FOTHER universities) Non-UK Individual (representing self) Non-UK Corporation Non-UK Entity that does not fit into any of the above (e.g. charities, schools, clubs, associations) Only applicable to businesses. (N = a number starting with 0 and is used to represent an ARRAY data structure): id Example 999 this is the id of the contact's record. =contacts_create; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; forename=my; surname=name; organisation=my Company; =me@me.com; address1=my Address; address2=; town=my Town; region=london; country=united Kingdom; postcode=aa1 11AA; phone= ; fax= ; usertype=ind; company_number= ; =ok ok=contact record for Mr Example has been removed. Contacts Delete This requires a contact ID and allows you to delete a contact record in your account. contacts_delete id ok pass phrase that supplied by the _get the ID for a contacts record that you wish to delete. ok a more detailed response about the record you've deleted. Example =contacts_delete; id=12345 =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; =ok ok=contact record for Mr Example has been removed.

12 Domain Management Domain List This returns a list of all the s you have in your account. s.n. s.n. s.n.created s.n.expires s.n.last_checked _list pass phrase that supplied by the _get The of this The name YYYY-MM-DD HH:MM:SS timestamp of the date this was first registered. YYYY-MM-DD HH:MM:SS timestamp of the expiry date for this. YYYY-MM-DD HH:MM:SS timestamp the last time this was checked by Daily. Example =_list; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; s.0.created= :00:00 s.0.last_checked= :32:18 s.0.=example.co.uk s.0.=live s.0.expires= :00:00 s.1.created= :00:00 s.1.last_checked= :59:34 s.1.=example.com s.1.=live s.1.expires= :00:00 Domain Lookup This allows you to check to see if a is available for registration. You can also supply the bulk flag and the will respond with the for all TLDs (this call will take longer to return the data due to the extra workload). _lookup example.com - A valid name. bulk yes or '' - optional, if supplied the will return the result for all TLDs. pass phrase that supplied by the _get Returns (not bulk) request: The name that you requested the lookup on. available, taken, error Returns for bulk request: bulk.n. The name that you requested the lookup on. TLDs include gb.net, biz, org.uk, net, web.com, de.com, asia,.ltd.uk, uk.net, tv, uk.com, com, cc, plc.uk, me.uk, org, eu.com, net.uk, us.com, tel, me, info, eu, mobi and co.uk. bulk.n. available, taken, error Example (not bulk) =_lookup; =example.com; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx;

13 Example (not bulk) Response: =example.com =taken Example bulk =_lookup; =example.com; bulk=yes; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; Example bulk Response: bulk.0.=example.gb.net bulk.0.=error bulk.1.=example.biz bulk.1.=taken bulk.2.=example.org.uk bulk.2.=taken bulk.3.=example.net bulk.3.=taken bulk.4.=example.web.com bulk.4.=available bulk.5.=example.de.com bulk.5.=error bulk.6.=example.gb.com bulk.6.=error Domain Register This allows you to register a using your credits. contact_id years order_id Example _register example.com - A valid available name. digit Your contacts can be seen using the contacts_list. digit Number of years to register this (.uk s default to 2 years). pass phrase that supplied by the _get the name that you requested the lookup on. ok or error this is the order id that can be used in conjunction with the order_check to see the of this transaction. =_register; =example.co.uk; contact_id=2; years=2; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; =example.co.uk =ok order_id=12345

14 Domain Transfer This allows you to transfer a into your account using your credits. contact_id order_id _transfer example.com - A valid available name. digit Your contacts can be seen using the contacts_list. pass phrase that supplied by the _get the name that you requested the lookup on. ok or error this is the order id that can be used in conjunction with the order_check to see the of this transaction. Example =_transfer; =example.co.uk; contact_id=2; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; =example.co.uk =ok order_id=12345 Domain Renew This allows you to renew a that's in your account. years order_id Example _renew example.com - A valid available name. digit Your contacts can be seen using the contacts_list. pass phrase that supplied by the _get the name that you requested the lookup on. ok or error this is the order id that can be used in conjunction with the order_check to see the of this transaction. =_renew; =example.co.uk; years=2 =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; =example.co.uk =ok order_id=12345

15 DNS Management Get DNS Records for Domain This will retrieve all the DNS records for the that you've supplied. dns_get pass phrase that supplied by the _get example.com - A name that is in your account. Returns (N = a number starting with 0 and is used to represent an ARRAY data structure): Example.com dns_records.n.data dns_records.n.type A dns_records.n.host www dns_records.n.id this id will be needed if you wish to edit this record (using the dns_set ). dns_records.n.mx_priority Example 5 this is only supplied if the dns_records.n.type is MX. =dns_get; =example.com; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx; =example.com dns_records.0.data=ns1.daily.co.uk. dns_records.0.type=ns dns_records.0.id=1 dns_records.0.host=@ dns_records.1.data=ns2.daily.co.uk. dns_records.1.type=ns dns_records.1.id=2 dns_records.1.host=@ dns_records.2.data=ns1.daily.co.uk. dns_records.2.type=soa dns_records.2.id=3 dns_records.2.host=@ dns_records.3.data=mx.daily.co.uk. dns_records.3.type=mx dns_records.3.id=4 dns_records.3.host=@ dns_records.3.mx_priority=5 dns_records.4.data= dns_records.4.type=a dns_records.4.id=5 dns_records.4.host=@ dns_records.5.data= dns_records.5.type=a dns_records.5.id=6 dns_records.5.host=www

16 Create a DNS Record for Domain This will allow you to create a DNS record for your (s). dns_set pass phrase that supplied by the _get example.com - A name that is in your account. action add record_data Data string for record data (eg ) record_host Data string for record host (eg www) record_type recrod_mx_priority A, MX, CNAME, etc A number between 1 and 99, only required if the record_type is equal to MX. example.com record_data record_type A record_host record_mx_priority Example www 5 this is only supplied if the record_type is MX. added =dns_set; =example.com; action=add; record_data= ; record_host=www; record_type=a; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx =example.com =added record_data= record_type=a record_host=www record_mx_priority=

17 Delete a DNS Record for Domain This will allow you to delete a DNS record. dns_set pass phrase that supplied by the _get action record_id example.com - A name that is in your account. delete The record id from dns_get example.com deleted Example =dns_set; =example.com; action=delete; record_id=12345 =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx =example.com =deleted Reset Zone for Domain This will allow you to reset the Zone to defaults for your. action Example dns_set pass phrase that supplied by the _get example.com - A name that is in your account. reset example.com deleted =dns_set; =example.com; action=reset; =ExAmPlExMpLeExAmPlExAmPlExAmPlExAmPlExAmPlExAmPlEx =example.com =reset Version 1.0 Revision 1.1 Initial release August 2012 Minor formatting changes