# HG changeset patch # User Heiko Schlittermann # Date 1632474955 -7200 # Node ID 4e431e2de91ab803f35f7522b20010b9919a0b32 # Parent 584ceb504d29431d79eb79cfa363c380c7cb57aa Project moved to https://gitea.schlittermann.de/IUS/joker-api-client.git diff -r 584ceb504d29 -r 4e431e2de91a Build.PL --- a/Build.PL Fri Sep 24 11:04:21 2021 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,16 +0,0 @@ -use 5.010; -use strict; -use warnings; -use Module::Build; - -Module::Build->new( - dist_name => 'Joker', - dist_version => 0, - dist_abstract => 'OO Interface to ask Joker.com', - requires => { - 'Moose' => 0, - 'MooseX::SemiAffordanceAccessor' => 0 - }, - script_files => [glob('bin/*')], -)->create_build_script; - diff -r 584ceb504d29 -r 4e431e2de91a MANIFEST --- a/MANIFEST Fri Sep 24 11:04:21 2021 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,11 +0,0 @@ -.hgignore -bin/joker-query -Build.PL -doc/DMAPI-ext.txt -joker.conf.example -lib/Joker.pm -lib/Joker/Result.pm -MANIFEST This list of files -MANIFEST.SKIP -README -t/10-joker.t diff -r 584ceb504d29 -r 4e431e2de91a README --- a/README Fri Sep 24 11:04:21 2021 +0200 +++ b/README Fri Sep 24 11:15:55 2021 +0200 @@ -1,1 +1,1 @@ -https://dmapi.joker.com/docs/DMAPI-ext.txt +Project moved to https://gitea.schlittermann.de/IUS/joker-api-client.git diff -r 584ceb504d29 -r 4e431e2de91a bin/joker-query --- a/bin/joker-query Fri Sep 24 11:04:21 2021 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,37 +0,0 @@ -#! /usr/bin/perl - -use 5.010; -use strict; -use warnings; -use Smart::Comments; -use Joker; - -my %conf = do 'joker.conf'; - -my $joker = Joker->new( - username => $conf{username}, - password => $conf{password}, -); - -my $x = $joker->request('query-whois', domain => shift); -say $x->code, ':', $x->status; -if ($x->code == 0) { - my %result = %{ $x->data }; - foreach (sort keys %result) { - say "$_: $result{$_}"; - } -} - -exit 0; - -### $x - -__END__ - -#say $joker->request('query-domain-list'); -my @results = map { (split)[1] } grep { /^\d/ } split /\r?\n/, - $joker->request('result-list', status => 'nack'); - -foreach (@results) { ### deleting: [===| ] [%] - $joker->request('result-delete', 'svtrid' => $_); -} diff -r 584ceb504d29 -r 4e431e2de91a doc/DMAPI-ext.txt --- a/doc/DMAPI-ext.txt Fri Sep 24 11:04:21 2021 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1013 +0,0 @@ -This is description of DMAPI, oriented mostly to experienced users. - -The description reflects interface version 1.2.* - -Basics: -======= - - Requests to the DMAPI (Domain Management API) are simply HTTP POST (or GET) - requests. - - NOTE: Only TLS is supported! - - 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 - - Server responses are plain-text messages, with headers (MIME-like), followed - by LF, followed by reply body, like this (response to login request): - ----reply--- -Auth-SID: - -com -net -org ----reply--- - - This way, even web-browsers might be used to send requests and to - read replies (may be useful for testing). - - Most common headers fields, returned by most requests: - -Tracking-Id: Unique server-assigned tracking id, assigned to almost all - requests. Please include this Id (if present) in case if - you are reporting problem related to failed request. -Status-Code: Not 0 if error occurred -Status-Text: Human-friendly error description -Result: ACK or NACK -Proc-ID: Joker.com processing ID, usually generated for all requests that - modify or create objects (domains/contacts/nameservers). -Account-Balance: - Current reseller's account balance. Please note, that - this value may be slightly outdated, and should be used - only as a reference. - -Error: May be returned if (and only if) the request was rejected, - in this case reason(s) will be provided. Presence of this - line in headers is indicative that processing didn't take - place. -Warning: Indicative of non-fatal processing or validation problems. - -Columns: List of columns names, separated by comma (for list queries) - If not present, see request description. -Separator: List column separator (TAB is "\t", SPACE is " ") - If not present, defaults to SPACE (or as specified in request) - - HTTP error codes: 200 if everything is OK (request was accepted and - processed or queued for processing), otherwise the reason will be - provided in Error header lines (or, if this is absent, HTTP error - code should be used). - - NOTE: Regardless of HTTP error code, please examine response body, - it may contain useful tips (in Error or Warning headers) why request - failed. - - IMPORTANT: Every request (except login) *requires* presence of - "auth-sid" parameter, which is returned by the "login" request. Active - session will expire after some inactivity period (default 1 hour). - - Example: - - https://dmapi.joker.com/request/query-domain-list?auth-sid=20ddb8c3b2ea758dcf9fa4c7f46c0784 - - In case if you use a browser to access this interface, then session id - will be send as a cookie, hence need not to be specified as Auth-Sid - (unless cookies are not supported or turned off). In any case, - "auth-sid" has precedence, if provided. - - NOTE: Session may become invalid due to various reasons, so please - don't expect it to be valid forever. Instead, design your application - in a way, that, if your request is rejected because of authorization - failure, send "login" request again, and only if it fails, stop processing. - - 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.). - - All variable and request names are case-insensitive. - -Differences to existing email-gateway -===================================== - - DMAPI only accepts pre-registered contact and name-server handles. - It means that before you can register (or modify) domain, you MUST - register all necessary contacts and name-servers. - - Unlike email interface, there is no differentiation in requests for - different domain/contact types. - - Some requests are asynchronous, and acceptance of request by the - DMAPI is not necessarily means that it is processed (or will be - processed at all). The real reply (acknowledgement or refusal) will - be stored on the server and can be retrieved later. To list - available replies you should use requests "result-list", - "result-retrieve" and "result-delete" periodically. - - NOTE: Not retrieved replies will be kept on the server for period of - 90 days, then only status of specific request will be available - (success or failure). - - IMPORTANT: Please also note that registration/renewal period is in - MONTHS, NOT YEARS! This is to allow future micro-registrations. - -DISCLAIMER -========== - - Please be aware, that, in some circumstances, your request might be - refused, not processed or processed incorrectly (unlikely, but still - possible). - - However, the DMAPI is supported feature, so your feedback is greatly - appreciated. - - By using DMAPI, you agree to General Terms & Conditions of Joker.com: - https://joker.com/index.joker?mode=page&page=agreement - -Requests, their parameters and return values -============================================ - -login -===== - Requires: - username Joker.com username - password Joker.com password - - Returns: - Auth-SID Authenticated Session ID, must be provided with any other request - UID Joker user-id - - List of supported TLDs which reseller may register. - - Authenticates user to the system. - - To be able to use entire API, you must have reseller account in - joker.com (and use this account to log in). - -logout -====== - - Returns: nothing - - Used to forcibly close (terminate) a session. The session identified by - Auth-SID may not be used anymore to send requests. Normally not required - as session will timeout eventually (default after 1 hour). - -result-list -=========== - - Accepts: - pending Shows results without reply (in progress) - showall Shows results deleted using result-delete - 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 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". - - All following filters may use patterns ("*" and "?") - - 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 specified SvTrId - cltrid Shows results for specified ClTrId - - Returns: - List of answers from joker.com (one per line): - - TimeStamp SvTrId Proc-ID request-type status ClTrId - - Where: - - TimeStamp: The time when request was made, YYYYMMDDHHMMSS - SvTrID: Tracking-Id associated with this request. - Proc-ID: Proc-Id associated with this request. - request-type: The type of the request. - request-object: The object name (host, domain or contact handle) - status: ack, nack or ?, where ack means that request was - completed successfully. - ClTrId: User specified transaction ID, or "-" if nothing - was provided by the user. - - -result-retrieve -=============== - - Accepts: - - Proc-ID One of this must be specified. If both are specified, - SvTrID SvTrId has precedence. - - Returns: - - Answer (processing result) associated with specified Tracking/Processing ID. - - If detailed information (content) is not available, only status will be returned. - - Please note: since there is no requirement of uniqueness for user-specified transaction - ids, it is not possible to use them to retrieve specific results. - -result-delete -============= - - Accepts: - - Proc-ID - SvTrId - - 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 any more when using result-list. - Semantics of parameters is like in result-retrieve. - -query-domain-list -================= - - Accepts: - pattern Pattern to match (glob-like) - from Start from this item in list - to End by this - showstatus Add additional column, showing domain status, - may be 0 or 1. - showgrants Add additional column, showing domain grants, - may be 0 or 1. - - Returns: - - List of registered domains and their expiration dates (one - 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 handle) - from Start from this item in list - to End by this - tld Limits output to contact handles which - may be used with specified TLDs. - extended-format Provides additional information for every contact listed: - name & organization. May be "1" or "0", defaults to "0". - - Returns: - - List of registered contact handles, one per line. - - NOTE: Unless explicitly requested ("from" and/or "to" parameters), the number - of entries returned is limited to 10000! - - When "extended-format" is requested, output columns are separated by tabs ("\t"), - and "Columns" header provides column names. - -query-ns-list, query-host-list -============================== - - Accepts: - pattern Pattern to match (against host name) - full Include IPs if non-zero - - Returns: - 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 "-". - - Example of list with IPs: - - ns.example.com 1.2.3.4 - - ns6.example.com - FE80:0000:0000:0000:0202:B3FF:FE1E:8329 - -query-object (deprecated; please use query-whois) -================================================= - - Accepts: - domain Domain name - contact Contact handle - host Host name - - Exactly one of those must be specified. Only object registered - with Joker.Com may be queried. - - Returns: - - Information about specified object (similar to whois), in format "key: value". - -query-whois -=========== - - Accepts: - domain Domain name - contact Contact handle - host Host name - - Exactly one of those must be specified. Only object registered - with Joker.Com may be queried. - - Returns: - - Information about specified object (similar to whois), in format "key: value". - The difference to query-object request is that this request reflects actual - (live) data in Joker.com database, while query-object may show a data which - is a bit outdated. - - NOTE: this request will eventually replace query-object, or, to be precise, query-object - will be replaced with this one. Some output fields are changed, some are removed - completely, but it should be compatible to query-object. Please, make a transition - to this request. - -query-profile -============= - - Returns reseller profile data in format "key: value". May be used to - query account balance. - - -contact-create -============== - - 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) - individual (opt) Y, Yes, N, No - organization (opt if individual) - email - address-1 - address-2 (opt) - city - state (opt) - postal-code - country ISO country code (2 letters) - phone Phone number - 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) - company-number (Required for .UK contacts with specific account types) - - "name" or "lname" and "fname" must be provided. Fields marked (opt) are - optional, all other fields are required (and must not be empty). - - As of version 1.1, "lname" and "fname", if provided, will be converted - to "name" (simple concatenation of "fname" and "lname"), because - registries support only "name" format. In general, use of "fname" and - "lname" is deprecated, and support for these fields will be removed - in version 1.2. - - Please note, fields listed here (except "tld") may be used (or required) - in other requests, this is indicated by referring to "Contact fields". - - "lang" must contain two-letter ISO country (language) code, and is only - required when creating .EU contacts. The purpose is to specify language - to be used in notifications emails, sent from EURid. Please note - this - field cannot be modified later, and the default is 'EN' (English)! - - "app-purpose", "nexus-category" and "nexus-category-country" are - required only when creating .US contacts, and cannot be modified - later. - - "account-type" is a required for all .UK contacts which will be used as - domain owner contacts. Possible values are: - - Value Meaning - ========== =========================================== - LTD UK Limited Company - PLC UK Public Limited Company - PTNR UK Partnership - STRA UK Sole Trader - LLP UK Limited Liability Partnership - IP UK Industrial/Provident Registered Company - IND UK Individual (representing self) - SCH UK School - RCHAR UK Registered Charity - GOV UK Government Body - CRC UK Corporation by Royal Charter - STAT UK Statutory Body - OTHER UK Entity that does not fit into any of the above - (e.g. clubs, associations, many universities) - FIND Non-UK Individual (representing self) - FCORP Non-UK Corporation - FOTHER Non-UK Entity - - By default, if "account-type" is not provided, value "FIND" or "IND" will be used - (dependent "country" value - for GB and UK it will be "IND", for everything else "FIND"). - - "company-number" is required when "account-type" is one of: SCH, RCHAR, LTD, PLC, LLP, IP - -contact-modify -============== - - Requires: - handle Contact handle to modify. - - Accepts (at least one of those must be provided): - name Full name (if empty, fname + lname will be used) - fname First name - lname Last name - title - individual Y, Yes, N, No - organization (must be provided if individual=N) - email - address-1 - address-2 - city - state - postal-code - country ISO country code (2 letters) - phone - fax - lang (only meaningful for .EU contacts) - app-purpose (.US contacts) - nexus-category (.US contacts) - nexus-category-country (.US contacts) - account-type (.UK contacts, if used as owner contact) - company-number (.UK contacts with specific account types) - - - If you specify a field, it will be used as a new value, if you omit - (don not specify) it, the old value will not be modified. - - See also "contact-create" request for additional information. - -contact-delete -============== - - Requires: - handle Contact handle to delete - - Using this request you can delete previously registered contact. - -ns-create, host-create -====================== - - Requires: - host FQDN host name - ip IPv4 address (must not be from IANA's reserved range) - ipv6 IPv6 address - - Using this request you can register a nameserver. If ipv6 is provided, ip (IPv4) must - be provided as well. - -ns-modify, host-modify -====================== - - Requires: - host FQDN host name - 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 - - Using this request you can delete a registered nameserver. - -domain-register -=============== - - Requires: - domain Domain name to register - period Registration period in MONTHS (not in years!) - status Domain status (only "production" is accepted so far) - owner-c Owner contact handle - billing-c Billing contact handle - admin-c Administrative contact handle - tech-c Technical contact handle - ns-list List of name servers, delimited by colon - - Accepts: - autorenew If set to "1", domain will be autorenewed upon - expiration. - language 3 letter language code for IDN domains - registrar-tag Registrar tag, also known as "Membership token", - only meaningful for .XXX domains - - - Using this request you can register the domain. - - NOTE: You *must* have registered contacts to be able to register a domain! - - IMPORTANT: Please note that registration period is in MONTHS, NOT YEARS! This - is to allow future micro-registrations (in development). - -domain-renew -============ - - Requires: - domain Domain name to renew - period Renewal period in months (not in years!) - expyear Wanted expiration year - - Using this request you can renew the domain. Please be aware that all - renewals are not refundable. - - IMPORTANT: Please note that registration period is in MONTHS, NOT YEARS! - - "expyear" is a safe option which can be used instead of "period" to - renew domain till specified year (not longer). If you use "period", - and by mistake send the request more than once, domain will be renewed - again, while with "expyear", it will not be renewed if it's expiration - year is greater or equals to specified. - - Only one of "period" or "expyear" may be used, but not both. - -domain-transfer-in-reseller -=========================== - - Requires: - domain Domain name to transfer - transfer-auth-id Transfer Auth Id - billing-c New billing contact handle - admin-c New admin contact handle - tech-c New tech contact handle - - Accepts: - status New domain status - owner-c New owner contact handle - autorenew Autorenew flag for the domain (0 or 1). - If not set explicitly, defaults to 1. - 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). - - "transfer-auth-id" is required for all domains excluding "uk" and "at". - - Please note that "owner-c" parameter will become mandatory one day, please - use it whenever possible. - -domain-transfer-get-auth-id -=========================== - - Requires: - domain Domain name to get auth id for - - 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. - - Please note - *every* request will generate new Auth-ID, thus - rendering any previously requested Auth-ID invalid. - -domain-modify -============= - - Requires: - domain Domain name to modify - - Accepts: - billing-c New billing contact handle - admin-c New administrative contact handle - tech-c New technical contact handle - ns-list List of new name-servers (it will _replace_ - existing name-servers!) - 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. - Value of "0" will remove DNSSEC, value of "1" will - add DNSSEC (and ds-N parameters must be provided) - - ds-1 List of DNSSEC parameters for DNSSEC enabled domains - ds-2 For com/net/org/tv/cc each entry has format: - ds-3 tag:alg:digest-type:digest - 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 name-servers or DNSSEC parameters (for DNSSEC enabled domains). - - If specific value is not present, it will not be touched. Modification - of name-servers or DNSSEC parameters will replace currently defined set - of DNSSEC keys or name-servers. - - NOTE: DNSSEC parameters (ds-N) must be specified in order (ds-1, ds-2 etc), - 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): - - http://dmapi.joker.com/request/domain-modify?domain=example.com&dnssec=1&ds-1=9934:8:1:C4BF75B16AF82888B61E28951BEF27804B60D968 - - Example for removing DNSSEC information: - - http://dmapi.joker.com/request/domain-modify?domain=example.com&dnssec=0 - - NOTE: You have to have your own name-service somewhere else to support DNSSEC, - 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 3 days. - type type of delete request, one of: - endoflife, immediate, transit - - Using this request you can delete already registered domain. - - If you delete a domain within the first 3 days after the registration, - the registration fee may be refunded to your account. - - To delete domain which is registered longer than 3 days, 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 to change owner - * Contact fields (see contact-create) - - Using this request you can change (visible) owner of the domain. - Please use same fields as in contact-create request to describe - new owner. - -domain-lock -=========== - - Requires: - domain Domain name to lock - - Using this request you can lock a domain for preventing fraudulent - transfer attempts. If a domain is locked, each transfer-request from - a foreign registrar will be declined. - -domain-unlock -============= - - Requires: - domain Domain name to unlock - - - Using this request you can unlock a domain. If you want to transfer a - domain to a foreign registrar, the domain has to be unlocked. - -domain-set-property -=================== - - Requires: - domain Domain name or pattern - pname Property name - pvalue Property value (may be empty) - - - Using this request you can set a property (flag) for a domain or - a set of domains, selected by wildcard pattern. - - List of available properties and their effects: - - Property name Value/Effect - ============= ============================================= - autorenew 0 or 1 - If set to 1, the domain will be autorenewed - on expiration (if you have non-zero balance). - - whois-opt-out 0 or 1 - Only meaningful for .tel domains currently. - If set to 1, owner information will not be - shown in whois. - - If value provided is empty, then the property will be cleared, i.e. - the default will be used. - -domain-get-property -=================== - - Requires: - domain Domain name - pname Property name (same as in - domain-set-property) - - Using this request you can query value of specific property set for - domain. It returns single line, which looks like: - - autorenew: 0 - -grants-list -=========== - - Requires: - domain Domain name - - Accepts: - showkey Show invitation access key - - Get a list of active and pending grants. - - Returns lines in the following format (space-separated): - - invitation domain - - - - grant domain - - Where: - Record number - Grant/Invite id (used to uniquely identify records for revocation) - Invitation access key, present *only* when "showkey" is non-zero - It has meaning only for pending invitations only, and always is "-" - for grants. - Domain name (identical to requested) - One of @admin/@billing/@tech/@creator - Self-explaining - Self-explaining - - - Self-Explaining - -grants-invite -============= - - Requires: - domain Domain name - email Email of invitee - client-uid Joker client-id of invitee - if provided, this will perform "silent" - assignment: invitee doesn't need to "accept" invitation, but will - be notified in any case. - role Proposed role (@admin/@billing/@tech/@creator) - nickname Invitee's nickname. If omitted, email will be used as default nickname. - - Returns status only (ok or not). Email is sent if request was succesfull. - - To internally transfer domain to another user (account) within Joker.com, please use the following - request: - - https://dmapi.joker.com/request/grants-invite?domain=example.com&email=dst-user-email@joker.com&role=@creator&client-uid= - - Obviously, you will need to know user ID of the user, who will receive the domain - simply providing email address - is not sufficient. - -grants-revoke -============= - - 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 successful. - -dns-zone-list -============= - - Accepts: - pattern Pattern to match (glob-like) - - List zones (domains) which are managed and served by Joker.com name - servers. Zones are listed one per line. - -dns-zone-get -============ - - Requires: - domain Zone (domain) name to fetch data - from. - - Returns list of zone records in the format, described in dns-zone-put request. - - -dns-zone-put -============ - - Requires: - 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 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. - - The format of a zone definition is as follows (one record per line): - -