ius/joker: comparison doc/DMAPI-ext.txt

equal deleted inserted replaced

-:e108c8bfb237
+:081ed0ce9532
 =======
 	Requests to the DMAPI (Domain Management API) are simply HTTP POST (or GET)
 	requests.
-	NOTE: Only SSL version 3 (or TLS v1) is supported, clients using
+	NOTE: Only TLS is supported!
-	      SSLv2 may (and most probably will) not work!
 	The request parameters are passed as standard www-form variables, URL
 	encoded, i.e. example for login request:
 		https://dmapi.joker.com/request/login?username=user@joker.com&password=pass
 	In request descriptions below, "Requires" section defines variables
 	(sometimes referred as fields) that MUST be present, "Accepts"
 	section defines variables that MAY be present (but not required),
 	and "Returns" section describes request output - header fields and
 	extra data (if any). If "Returns" is omitted, then standard reply
-	should be expected (Status-Code, Status-Text, Proc-ID etc).
+	should be expected (Status-Code, Status-Text, Proc-ID etc.).
 	All variable and request names are case-insensitive.
 Differences to existing email-gateway
 =====================================
 ===========
 	Accepts:
 		pending			Shows results without reply (in progress)
 		showall			Shows results deleted using result-delete
-		period			Shows results for specifed period of days (default 90)
+		period			Shows results for specified period of days (default 90)
 		date			Shows results received on (or before) specified date.
 					When date is specified, parameter "period" will be
 					applied to this date (instead of today) and defaults
 					to 1.
-		offset			Start dispalying results from specified position
+		offset			Start displaying results from specified position
 		limit			Sets limit for number of rows displayed
 		status			Shows results having specified status (ack/nack/?)
 		count-only		When set to 1, only count number of records and return
 					single line in format "Records: N".
 		rtype			Shows results for requests of specified type
 					(domain-register/etc)
 		objid			Shows results for specified object ids (domain names
 					and so on)
 		procid			Shows results for specified proc-id
-		svtrid			Shows results for specifued SvTrId
+		svtrid			Shows results for specified SvTrId
 		cltrid			Shows results for specified ClTrId
 	Returns:
 		List of answers from joker.com (one per line):
 	Returns:
 		A descriptive message (confirmation) in case of success.
 	This request will delete the content (not the status) of reply to asynchronous
-	request. Deleted results will not be listed anymore when using result-list.
+	request. Deleted results will not be listed any more when using result-list.
 	Semantics of parameters is like in result-retrieve.
 query-domain-list
 =================
 					may be 0 or 1.
 	Returns:
 		List of registered domains and their expiration dates (one
-		per line, separated by whitespace). If "showstatus" is present,
+		per line, separated by white-space). If "showstatus" is present,
 		the the list will be with three columns, the last one showing
 		domain status (like "lock,autorenew" etc - comma separated).
 query-contact-list
 ==================
 	Accepts:
 		pattern			Pattern to match (against host name)
 		full			Include IPs if non-zero
 	Returns:
-		List of registered name servers, one perl line
+		List of registered name servers, one per line
 		If "full" is non-zero, then the list will include IP addresses,
 		IPv4 (2nd column) and IPv6 (3rd column), columns will be separated
 		by tab ("\t") character. If specific IP is not present (say, there
 		is only IPv4 or IPv6), it will be listed as "-".
 contact-create
 ==============
-	Requires:
+	Parameters:
 		tld			Target TLD, where this contact is intended to be used.
 		name			Full name (if empty, fname + lname will be used)
 		fname			First name
 		lname			Last name
 		title			(opt)
 		address-2		(opt)
 		city
 		state			(opt)
 		postal-code
 		country			ISO country code (2 letters)
-		phone
+		phone			Phone number
-		fax			(opt)
+		fax			Fax number (opt)
 		lang			(only meaningful for .EU contacts)
 		app-purpose		(required for .US contacts)
 		nexus-category		(required for .US contacts)
 		nexus-category-country	(required for .US contacts)
 		account-type		(required for .UK contacts, if used as owner contact)
 		ip			IPv4 address (must not be from IANA's reserved range)
 		ipv6			IPv6 address
 	Using this request you can modify the IP address of a registered
 	nameserver.
+	"-" may be used to specify empty value for "ip" or "ipv6", but at least one
+	of IP addressses must be set to valid address, or the request will fail.
 ns-delete, host-delete
 ======================
 	Requires:
 		host			FQDN host name
 	Accepts:
 		autorenew		If set to "1", domain will be autorenewed upon
 					expiration.
 		language		3 letter language code for IDN domains
-		registrar-tag		Ragistrar tag, also known as "Membership token",
+		registrar-tag		Registrar tag, also known as "Membership token",
 					only meaningful for .XXX domains
 	Using this request you can register the domain.
 	Accepts:
 		status			New domain status
 		owner-c			New owner contact handle
 		autorenew		Autorenew flag for the domain (0 or 1).
-					If not set explicity, defaults to 1.
+					If not set explicitly, defaults to 1.
-		ns-list			List of colon-separated nameservers.
+		ns-list			List of colon-separated name-servers.
 		owner-email		New owner email
 	Using this request you can initiate a transfer of the domain from
 	another registrar to Joker.com (gaining or incoming transfer).
 ===========================
 	Requires:
 		domain			Domain name to get auth id for
-	Retrieves domain Auth-ID, which is required when transfering domains
+	Retrieves domain Auth-ID, which is required when transferring domains
 	to another registrar.
 	This request is not real-time, i.e. you have to check detailed reply
 	(use "result-retrieve")	to get Auth-ID.
 	Accepts:
 		billing-c		New billing contact handle
 		admin-c			New administrative contact handle
 		tech-c			New technical contact handle
-		ns-list			List of new nameservers (it will _replace_
+		ns-list			List of new name-servers (it will _replace_
-					existing nameservers!)
+					existing name-servers!)
-		registrar-tag		Ragistrar tag, also known as "Membership token",
+		registrar-tag		Registrar tag, also known as "Membership token",
 					which can be set/changed on .XXX domains
 		dnssec			If specified, allows setting or removal of DNSSEC
 					keys for domain. If not specified, DNSSEC records
 					will not be changed.
 		ds-4			For de:
 		ds-5				protocol:alg:flags:pubkey-base64
 		ds-6
 	Using this request you can modify contact handles for the domain,
-	list of nameservers or DNSSEC parameters (for DNSSEC enabled domains).
+	list of name-servers or DNSSEC parameters (for DNSSEC enabled domains).
 	If specific value is not present, it will not be touched. Modification
-	of nameservers or DNSSEC parameters will replace currently defined set
+	of name-servers or DNSSEC parameters will replace currently defined set
-	of DNSSEC keys or nameservers.
+	of DNSSEC keys or name-servers.
 	NOTE: DNSSEC parameters (ds-N) must be specified in order (ds-1, ds-2 etc),
-	and due to techinical limitations this is impossible to modify only specific
+	and due to technical limitations this is impossible to modify only specific
 	key - they must be set all at once. This means that any request to modify DNSSEC
 	records will *replace* existing keys with only those which are provided!
 	Example for adding one key (and enabling DNSSEC):
 	Example for removing DNSSEC information:
 	http://dmapi.joker.com/request/domain-modify?domain=example.com&dnssec=0
-	NOTE: You have to have your own nameservice somewhere else to support DNSSEC,
+	NOTE: You have to have your own name-service somewhere else to support DNSSEC,
-	if you use Joker.com nameservice, DNSSEC will not be provided!
+	if you use Joker.com name-service, DNSSEC will not be provided!
 domain-delete
 =============
 	Requires:
 		domain			Domain name to delete
 	Accepts:
 		force			If present and contains 1, Y or Yes,
 					domain will be deleted even if older
-					that 72 hours.
+					that 3 days.
 		type			type of delete request, one of:
 					endoflife, immediate, transit
+	Using this request you can delete already registered domain.
-	Using this request you can delete the domain.
+	If you delete a domain within the first 3 days after the registration,
-	If you delete a domain within the first 72 hours after the
+	the registration fee may be refunded to your account.
-	registration, the registration-fee will be refunded to your account.
+	To delete domain which is registered longer than 3 days, you must
-	IMPORTANT: .EU domain registration is irreversible, i.e. you will NOT
-	be refunded if you delete .EU domain even withing 72 hours after
-	creation.
-	To delete domain which is registered longer than 72 hours, you must
 	specify "force=1", otherwise request will be rejected.
+	IMPORTANT: Please note that this feature must not be used for "domain tasting"
+	or "front running", and if you delete more than 1 domain per 12 registered
+	per month, you will not be refunded!
+	Deletion of domains in zones .eu, .nl, .me, .at, .de will not be refunded
+	regardless of when it was deleted!
 domain-owner-change
 ===================
 	Requires:
 		domain			Domain name
 		role			Role to revoke
 		scope			Scope (from grants-list request)
 		type			Type of the record to revoke - "grant" or "invitation"
-	Returns status only (ok or not). Email is sent if request was succesfull.
+	Returns status only (ok or not). Email is sent if request was successful.
 dns-zone-list
 =============
 	Accepts:
 		domain			Zone (domain) name to store data to.
 		zone			URL encoded zone data
 	Replace current zone for provided domain with specified value.
-	Field "zone" will be parsed as multiline text (so usual line
+	Field "zone" will be parsed as multi-line text (so usual line
 	terminators are expected).
 	WARNING: this request will OVERWRITE current zone, i.e. all current
 	records will be replaced by new records.
 	if the answer is "no", then verification status is set to "invalid". If there is no answer before
 	verification deadline (normally 15 days), the status is also set to "invalid".
 	Returns special response header "Result", which will contain "ACK" if the verification has been
 	accepted or "NACK" otherwise.
+wa-email-query-status
+=====================
+	Requires:
+		email	Email address to query status of
+	Returns single line with email status. Possible statuses:
+	verified	email address is known and successfully verified (valid)
+	unverified	email address is either not (yet) verified or is not known.
+	pending		verification email has been sent but no response received yet
+	invalid		email address is known to be invalid (bounced or no response)
+	Statuses "pending" and "invalid" are informational and are not guaranteed,
+	i.e. it could happen that "unverified" is returned instead.
 -----

changeset 9	081ed0ce9532
parent 4	08a632c3244f