API Explanation
===============

1. DNSPod Users' API,aim to help the users to manage their domains conveniently,are limited to personal users to use.
3. No third-party applications or users are allowed to use this API. If you have needs,please let us know: https://www.dnspod.com/About/Aboutus .


API Development Norm
--------------------    

1. Misuse:
    This will be looked as API misuse. Including but not limit to:
        * Do a lot of inserts,deletes,updates or refreshes within a short time.
        * Request a lot without changing anything. What are you thinking!
        * Too many useless or repeated requests caused by wrong logic or endless loops.
        * Other requests that may give us a lot of pressure.

    In order to ensure you and other developers' benefits,please use our APIs legitimately. DNSPod will punish the behaviors like API misuse by prohibit the accounts and reserve all the rights to arbitrate.`

2. Login Disable:
    If there are more than 30 login failures within 5 minutes,the account will be disabled to login again for an hour. Please check the login status when you develop your own applications,and stop trying if fails.

3. Prohibition:
    Even got prohibited,you can still use it on the official website. The prohibition will be relieved an hour later.Please be careful and never use it for large tests. 

4. Requests:
    * The request url starts with "https://dnsapi.cn/",which based on SSL. You must use "https" instead of "http".
    * POST method accepted only.
    * Please use UTF-8 encoding for data transfer. The responses are also UTF-8 encoded.

5. UserAgent:
    * The UserAgent must be set. Prohibition may caused by wrong UserAgent or none.
    * UserAgent Format:Application Name/Version(email). For example:"MJJ DDNS Client/1.0.0 (shallwedance@dnspod.com)".

6. Security:
    Almost every step needs the email address and the password. So if you have to storage the user's informations,please encrypt the password first. Never storage the password directly.

7. Support:
    * Support center: https://www.dnspod.com/Support



Global Parameters
-----------------
All the APIs need this parameters.
    * **format** {json,xml} The format of response.Default "xml". "json" is highly recommended.Optional parameter.
    * **error_on_empty** {yes,no} Whether to response an error when there's no results.
    * **user_token** The user token obtained with the ``Auth`` command.

Common Response Codes
---------------------
Those responses codes could be in any API because they are the common responses.
    * -1 Login fails.
    * -2 API used too frequently.
    * -3 Invalid agent.(only works for agent users)
    * -4 Not in this agent.(only works for agent users)
    * -7 No permission to use this API.
    * -8 Account got prohibited.
    * 85 Account logged-on in another place and your request got rejected.
    * -99 This API is not ready to be used.No rush.
    * 1 Action completed successfully.
    * 2 POST method only.
    * 3 Unknown errors.
    * 6 Invalid user_id.(only works for agent users)
    * 7 User is not under this agent.(only works for agent users)

Get the user token
------------------
Before you use the APIs, you need get a user-token first by this one.

URL:
    * https://api.dnspod.com/Auth
HTTP Request Type:
    * POST
Request Parameters:
    * **format** {json,xml} The format of response.Default "xml". "json" is highly recommended.Optional parameter.
    * **error_on_empty** {yes,no} Whether to response an error when there's no results.
    * **login_email** The login email. Mandatory parameter.
    * **login_password** The login password. Mandatory parameter.
    * **login_code** The code that generated by the D-Token. Mandatory parameter.
    * **login_remember** {yes,no} Whether to remember the D-Token code.Default "yes".
    * **user_id** The user's ID. A must for agent users, and a waste for regular users.
Response Code:
    * Common Response Codes
    * 10001 User have been spammed
    * 10003 Account email is invalid
    * 10004 Password's length is invalid, must between 6 and 32
    * 10005 Account is not exist

Example::
    
    curl -X POST https://api.dnspod.com/Auth -d 'login_email=api@dnspod.com&login_password=password&format=json'

Response Example:

    * JSON::

        {
            "status": {
                "code": "1",
                "message": "Action completed successful",
                "created_at": "2014-06-04 20:37:31"
            },
            "user_token": "730060,e1a8a$f14dc5dcbafd83680b3d2a553c4d553d"
        }


D-Token
-------
Users that already turned the D-Token on need this parameters in the request:
    * **login_code** The code that generated by the D-Token. Mandatory parameter.
    * **login_remember** {yes,no} Whether to remember the D-Token code.Default "yes".

Attention:
    Since the D-Token code changes every 30 seconds,it is highly recommended that you set the "login_remember" to "yes".If so,you will get an extra response with the format of "t + user_id" like "t123456",whose life last for a month.With this cookie,you don't need to submit the "login_code" and "login_remember".

If you are using D-Token,this error codes might be responded.
    * 50 You already turned the D-Token on,and we need you D-Token code.
    * 51 You hasn't turned the D-Token on.
    * 52 Invalid login code.
    * 53 You already turned the D-Token on.
    * 54 The owner has turned the D-Token on,and so should you.



Get the Version of API
----------------------
URL:
    * https://api.dnspod.com/Info.Version
HTTP Request Type:
    * POST
Request Parameters:
    * Global Parameters
Response Code:
    * Common Response Codes

Example::
    
    curl -X POST https://api.dnspod.com/Info.Version -d 'user_token=730060,e1a8a$f14dc5dcbafd83680b3d2a553c4d553d&format=json'

Response Example:

    * JSON::

        {
            "status": {
                "code": "1",
                "message": "4.6",
                "created_at": "2014-06-04 20:40:37"
            }
        }