NAME

Regru::API - Perl bindings for Reg.ru API v2

VERSION

version 0.042

SYNOPSIS

my $client = Regru::API->new(
    username => 'test',
    password => 'test',
);

# trivial API request
my $resp = $client->nop;

if ($resp->is_success) {
    print $response->get('user_id');
}
else {
    print "Error code: " . $resp->error_code . ", Error text: " . $resp->error_text;
}

DESCRIPTION

Regru::API implements simplified access to the REG.API v2 provided by REG.RU LLC. This is a JSON-driven implementation. Input/output request data will transforms from/to JSON transparently.

Rate limiting

Rate limiting in version 2 of the REG.API is considered on a per-user and per-ip basic. The REG.API methods have not divided into groups by limit level. There is no difference between them. At the moment REG.API v2 allows to execute 1200 requests per-user and per-ip within 1 hour window. Both limits are acting at the same time. If the limits has exceeded then REG.API sets the error code (depends on kind of) to IP_EXCEEDED_ALLOWED_CONNECTION_RATE or ACCOUNT_EXCEEDED_ALLOWED_CONNECTION_RATE which might be checked via attribute error_code.

The following tips are there might helps to reduce the possibility of being rate limited:

Caching

Store all domain name or service related data locally and use the REG.API in cases you want to change some data in the registry (e.g. contact data, DNS servers, etc).
Bulk requests

Group similar items and execute a bulk API request. A bunch of methods supports sending request for the list of items at the same time (e.g. multiple domain names). Check the details at REG.API Service list identification parameters.
Journaling

Keep the logs of interactions with REG.API (requests and responses). This will helps quickly resolve the issues instead of sending additional requests to find out what's happened.

Categories (namespaces)

REG.API methods are divided into categories (namespaces). When you wish to make an API request to some REG.API method, that belongs to some namespace (category) you should get a namespace handler (defined as trivial client's method):

# suppose we already have a client
$client->user->nop;

# or like this
$zone = $client->zone;
$zone->register_ns(...);

At the moment there are the following namespaces:

root

General purpose methods such as "nop", "reseller_nop" etc which are described below. Actually is a virtual namespace defined by client. No needs to get namespace handler. The methods of this namespace are available as client's methods directly.
```
  $client->nop;
  $client->reseller_nop;
```
See ["REG.API METHODS"](#REG.API METHODS).
user

User account management methods.
```
  # suppose we already have a client
  $client->user->nop;
```
See Regru::API::User for details and REG.API Account management functions.

domain

Domain names management methods.

  # suppose we already have a client
  $client->domain->get_nss(
      domain_name => 'gallifrey.ru',
  );

See Regru::API::Domain for details and REG.API Domain management functions.

zone

DNS resource records management methods.
```
  # suppose we already have a client
  $client->zone->clear(
      domain_name => 'pyrovilia.net',
  );
```
See Regru::API::Zone for details and REG.API DNS management functions.

service

Service management methods.

  # suppose we already have a client
  $client->service->delete(
      domain_name => 'sontar.com',
      servtype    => 'srv_hosting_plesk',
  );

See Regru::API::Service for details and REG.API Service management functions.

folder

User folders management methods.
```
  # suppose we already have a client
  $client->folder->create(
      folder_name => 'UNIT',
  );
```
See Regru::API::Folder for details and REG.API Folder management functions.
bill

Invoice management methods.
```
  # suppose we already have a client
  $client->bill->get_not_payed(
      limit => 10,
  );
```
See Regru::API::Bill for details and REG.API Invoice management functions.

Methods accessibility

All REG.API methods can be divided into categories of accessibility. On manual pages of this distibution accessibility marked by scope tag. At the moment the following categories of accessibility present:

everyone

All methods tagged by this one are accessible to all users. Those methods does not require authentication before call.
clients

This tag indicates the methods which accessible only for users registered on reg.com website. Strongly required an authenticated API request.
partners

Group of methods which accessible only for partners (resellers) of the REG.RU LLC. Actually, partners (resellers) able to execute all methods of the REG.API without any restrictions.

Request parameters

Each API request should contains a set of parameters. There are the following parameters:

authentication parameters

These parameters are mandatory for the each method that requires authentication. This group of parameters includes username and password. Both parameters should be passed to the constructor and their will be added to API request.
management parameters

This group include parameters defines input/output formats, encodings and language prefecence. Some parameters are fixed to certains values, some might be set via passing values to the constructor: see io_encoding and lang options.
service identification parameters

The group of parameters with aims to point to the particular service or group of services such as domain names, folders, etc. Should be passed to an API request together with method specific parameters.

More info at REG.API Service identification parameters
method specific parameters

Parameters applicable to a particular API method. Very wide group. Strongly recommended to consult with REG.API documentation for each method before perform an API request to it. The distribution's manual pages includes links to documentation for each API method call. The main source for the method specific parameters available at REG.API General description of functions.

Response parameters

Response parameters of the API request automatically handles by Regru::API::Response module. There is no reasons to do some addtional work on them. Each response may contains the following set of fileds:

result

The result of API request. Either success or error. Can be accessed via attribute is_success in boolean context.
answer

The answer of API method call. May appear only when result of API request was successful. Can be accessed via attribute answer. Default value is {} (empty HashRef). Gets assigned a default value if result of API request was finished with error.
error_code

The error code of API method call. May appear only when result of API request finished with error. Can be accessed via attribute error_code. See details at REG.API Common error codes.
error_text

The short description of error. The language depends on option lang "new" passed to constructor. May appear only when result of API request finished with error. Can be accessed via attribute error_text. See details at REG.API Common error codes.
error_params

Additional parameters included to the error. May appear only when result of API request finished with error. Can be accessed via attribute error_params.

Access to REG.API in test mode

REG.RU LLC provides an access to REG.API in test mode. For this, might be used a test account with username and password equals to test.

my $client = Regru::API->new(username => 'test', password => 'test');
# we're in test mode now
$client->domain->get_prices;

In the test mode REG.API engine (at server-side) handles API request: ensures necessary checks of input parameters, produces response but actually does not perform any real actions/changes.

Also, for debugging purposes REG.API provides a special set of methods allows to ensure the remote system for availability without workload at minimal response time. Each namespace has method called nop for that.

METHODS

new

Creates a client instance to interract with REG.API.

my $client = Regru::API->new(
    username => 'Rassilon',
    password => 'You die with me, Doctor!'
);

my $resp = $client->user->get_balance;

print $resp->get('prepay') if $resp->is_success;

# another cool code...

Available options:

username

Account name of the user to access to reg.com website. Required. Should be passed at instance create time. Although it might be changed at runtime.
```
  my $client = Regru::API->new(username => 'Cyberman', password => 'Exterminate!');
  ...
  # at runtime
  $client->username('Dalek');
```
password

Account password of the user to access to reg.com website or an alternative password for API defined at Reseller settings page. Required. Should be passed at instance create time. Although it might be changed at runtime.
```
  my $client = Regru::API->new(username => 'Master', password => 'Doctor');
  ...
  # at runtime
  $client->password('The-Master.');
```

io_encoding

Defines encoding that will be used for data exchange between the Service and the Client. At the moment REG.API v2 supports the following encodings: utf8, cp1251, koi8-r, koi8-u, cp866. Optional. Default value is utf8.

  my $client = Regru::API->new(..., io_encoding => 'cp1251');
  ...
  # or at runtime
  $client->io_encoding('cp1251');

  my $resp = $client->user->create(
      user_login      => 'othertest',
      user_password   => '111',
      user_email      => 'test@test.ru',
      user_first_name => $cp1251_encoded_name
  );

lang

Defines the language which will be used in error messages. At the moment REG.API v2 supports the following languages: en (English), ru (Russian) and th (Thai). Optional. Default value is en.

  my $client = Regru::API->new(..., lang => 'ru');
  ...
  # or at runtime
  $client->lang('ru');

  $client->username('bogus-user');
  print $client->nop->error_text; # -> "Ошибка аутентификации по паролю"

debug

A few messages will be printed to STDERR. Default value is 0 (suppressed debug activity).

  my $client = Regru::API->new(..., debug => 1);
  ...
  # or at runtime
  $client->debug(1);

user

Returns a handler to access to REG.API user account management methods. See Regru::API::User.

domain

Returns a handler to access to REG.API domain name management methods. See Regru::API::Domain.

zone

Returns a handler to access to REG.API DNS resource records management methods. See Regru::API::Zone.

service

Returns a handler to access to REG.API service management methods. See Regru::API::Service.

folder

Returns a handler to access to REG.API folder management methods. See Regru::API::Folder.

bill

Returns a handler to access to REG.API invoice management methods. See Regru::API::Bill.

namespace_handlers

Creates shortcuts to REG.API categories (namespaces). Used internally.

REG.API METHODS

nop

For testing purposes. Scope: everyone. Typical usage:

$resp = $client->nop;

Answer will contains an user_id and login fields.

More info at Common functions: nop.

reseller_nop

Similar to previous one but only for partners. Scope: partners. Typical usage:

$resp = $client->reseller_nop;

Answer will contains an user_id and login fields.

More info at Common functions: nop.

get_user_id

Get the identifier of the current user. Scope: clients. Typical usage:

$resp = $client->get_user_id;

Answer will contains an user_id field.

More info at Common functions: nop.

get_service_id

Get service or domain name identifier by its name. Scope: clients. Typical usage:

$resp = $client->get_service_id(
    domain_name => 'teselecta.ru',
);

Answer will contains a service_id field or error code if requested domain name/service not found.

More info at Common functions: nop.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/regru/regru-api-perl/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHORS

Polina Shubina shubina@reg.ru
Anton Gerasimov a.gerasimov@reg.ru

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

Rate limiting

Categories (namespaces)

Methods accessibility

Request parameters

Response parameters

Access to REG.API in test mode

METHODS

new

user

domain

zone

service

folder

bill

namespace_handlers

REG.API METHODS

nop

reseller_nop

get_user_id

get_service_id

SEE ALSO

BUGS

AUTHORS

COPYRIGHT AND LICENSE