Welcome to transip-api’s documentation!¶

This library aims to implement the TransIP SOAP V5 API in Python. The SOAP V5 API is marked as deprecated by TransIP, users are strongly advised to switch to the new TransIP REST API V6.

If you would like to use the new TransIP REST API V6, please consider using python-transip instead.

Here is an example of a simple Python program:

from transip.service.vps import VpsService


PRIVATE_KEY = '''
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
'''

# You can specify the private key directly or supply the path to the private
# key file. The private_key_file will default to `decrypted_key`.
client = VpsService('accountname', private_key_file='/path/to/decrypted_key')
client = VpsService('accountname', private_key=PRIVATE_KEY)

# Order a Vps without addons:
client.order_vps('vps-bladevps-x1', None, 'ubuntu-18.04', 'vps-name')

You can get the library directly from PyPi:

pip install transip

Documentation¶

This part of the documentation guides you through all of the library’s usage patterns.

Quickstart¶

You can get the library directly from PyPI:

pip install transip-api

The installation into a virtualenv is heavily recommended.

virtualenv¶

Virtualenv is probably what you want to use for developing Python applications. Simply fire up a shell and create your own isolated Python environment in the venv folder:

$ mkdir myproject
$ cd myproject
$ python -m venv venv

Now, whenever you want to work on a project, you only have to activate the corresponding environment. On Mac OS X and Linux, do the following:

$ . venv/bin/activate

If you are on Windows, use the following command:

$ venv\scripts\activate

Either way, you should now be using your virtualenv (notice how the promt of you shell has changed to show the active environment).

And if you want to exit your virtualenv, use the following command:

$ deactivate

Enter the following command to get transip-api installed in your virtualenv:

$ pip install transip

A few seconds later and your are good to go.

Command-line interpreter¶

The transip-api includes a command-line interpreter (CLI) that doesn’t do much yet. By default it does a getDomainNames() call, but with the -u option it’s also possible to add or update DNS records. When calling it with the -h, it will show all available options.

$ transip-api
[example.com, example.org, example.net]

$ transip-api -h
usage: transip-api [-h] [-l LOGINNAME] [-s] [-a] [-u] [-d]
                   [--domain-name DOMAIN_NAME] [--entry-name ENTRY_NAME]
                   [--entry-expire ENTRY_EXPIRE] [--entry-type ENTRY_TYPE]
                   [--entry-content ENTRY_CONTENT] [--api-key PRIVATE_KEY_FILE]

optional arguments:
  -h, --help            show this help message and exit
  -l LOGINNAME, --login-name LOGINNAME
                        TransIP username
  -s, --show-dns-entries
                        show all DNS entries for a domain
  -a, --add-dns-entry   add an entry in the DNS
  -u, --update-dns-entry
                        update an entry in the DNS
  -d, --delete-dns-entry
                        delete an entry in the DNS
  --domain-name DOMAIN_NAME
                        domain name to use
  --entry-name ENTRY_NAME
                        name of the DNS entry
  --entry-expire ENTRY_EXPIRE
                        expire time of the DNS entry
  --entry-type ENTRY_TYPE
                        type of the DNS entry
  --entry-content ENTRY_CONTENT
                        content of the DNS entry
  --api-key PRIVATE_KEY_FILE
                        TransIP private key

Example of adding/updating a record:

$ transip-api -l githubuser -u --api-key privatekey --domain-name example.com --entry-name testentry --entry-expire 86400 --entry-type A --entry-content 127.0.0.1
Request finished successfully.

API¶

This part of the documentation lists the full API reference of all public classes and functions.

Client¶

class transip.client.Client(service_name, login, private_key=None, private_key_file='decrypted_key', endpoint='api.transip.nl')¶

A client-base class, for other classes to base their service implementation on. Contains methods to set and sign cookie and to retrieve the correct WSDL for specific parts of the TransIP API.

Note:

You either need to supply a private_key or a private_key_file.

Args:

service_name (str): Name of the service. login (str): The TransIP username. private_key (str, optional): The content of the private key for

accessing the TransIP API.

private_key_file (str, optional): Path the the private key for: accessing the TransIP API. Defaults to ‘decrypted_key’.

endpoint (str): The TransIP API endpoint. Defaults to ‘api.transip.nl’.

build_cookie(method, mode, parameters=None)¶

Build a cookie for the request.

Keyword arguments: method – the method to be called on the service. mode – Read-only (MODE_RO) or read-write (MODE_RW)

update_cookie(cookies)¶: Updates the cookie for the upcoming call to the API.

Services¶

class transip.service.domain.DomainService(*args, **kwargs)¶

Representation of the DomainService API calls for TransIP

add_dns_entries(domain_name, dns_entries)¶: Adds the given DnsEntries to the domain. :type domain_name: str :type dns_entries: list of transip.service.objects.DnsEntry

batch_check_availability(domain_names)¶: Transip_DomainService::batchCheckAvailability Allows only 20 domain names per request :type domain_names: list of str :rtype: list of transip.service.objects.DomainCheckResult

batch_get_info(domain_names)¶: Transip_DomainService::batchGetInfo :type domain_names: list of str :rtype: list of transip.service.objects.Domain

cancel(domain_name, end_time)¶: Transip_DomainService::batchGetInfo :type domain_name: str :type end_time: datetime.datetime

cancel_domain_action(domain)¶: Transip_DomainService::cancelDomainAction :type domain: transip.service.objects.Domain

check_availability(domain_name)¶: Transip_DomainService::checkAvailability :type domain_name: str :rtype: str the availability status of the domain name

get_all_tld_infos()¶: Transip_DomainService::batchGetInfo :rtype: list of transip.service.objects.Tld

get_auth_code(domain_name)¶: Transip_DomainService::getAuthCode :type domain_name: str :rtype: str

get_current_domain_action(domain_name)¶: Transip_DomainService::getCurrentDomainAction :type domain_name: str :rtype: transip.service.objects.DomainAction

get_domain_names()¶: Transip_DomainService::getDomainNames :rtype: list of str

get_info(domain_name)¶: Retrieves information about the requested domain-name. :param domain_name: str :rtype: transip.service.objects.Domain

get_is_locked(domain_name)¶: Transip_DomainService::getIsLocked (@deprecated use getInfo) :type domain_name: str :rtype: bool

get_tld_info(tld_name)¶: Transip_DomainService::getTldInfo :type tld_name: str :rtype: transip.service.objects.Tld

get_whois(domain_name)¶: Transip_DomainService::getWhois :type domain_name: str :rtype: str

register(domain)¶

remove_dns_entries(domain_name, dns_entries)¶: Removes the given DnsEntries from the domain. :type domain_name: str :type dns_entries: list of transip.service.objects.DnsEntry to remove, cannot be empty

retry_current_domain_action_with_new_data(domain)¶: Transip_DomainService::retryCurrentDomainActionWithNewData :type domain: transip.service.objects.Domain

retry_transfer_with_different_auth_code(domain, new_auth_code)¶: Transip_DomainService::retryTransferWithDifferentAuthCode :param domain: transip.service.objects.Domain :type new_auth_code: str

set_contacts(domain_name, contacts)¶: Transip_DomainService::setContacts :type domain_name: str :type contacts: list of transip.service.objects.WhoisContact

set_dns_entries(domain_name, dns_entries)¶: Sets the DnEntries for this Domain, will replace ALL existing dns entries with the new entries :type domain_name: str :type dns_entries: list of transip.service.objects.DnsEntry

set_lock(domain_name)¶: Transip_DomainService::batchGetInfo :type domain_name: str

set_nameservers(domain_name, nameservers)¶: Transip_DomainService::batchGetInfo :type domain_name: str :type nameservers: list of transip.service.objects.Nameserver

set_owner(domain_name, registrant_whois_contact)¶: Transip_DomainService::batchGetInfo :type domain_name: str :type registrant_whois_contact: transip.service.objects.WhoisContact

transfer_with_owner_change(domain, auth_code)¶: Transip_DomainService::transferWithOwnerChange :type domain: transip.service.objects.Domain :type auth_code: str

transfer_without_owner_change(domain, auth_code)¶: Transip_DomainService::transferWithoutOwnerChange :type domain: transip.service.objects.Domain :type auth_code: str

unset_lock(domain_name)¶: Transip_DomainService::batchGetInfo

class transip.service.haip.HaipService(*args, **kwargs)¶

Representation of the HaipService API calls for TransIP

change_haip_vps(haip_name, vps_name)¶: Changes the VPS connected to the HA-IP

get_haip(haip_name)¶: Get a HA-IP by name

get_haips()¶: Get all HA-IPs

class transip.service.vps.VpsService(*args, **kwargs)¶

Representation of the VpsService API calls for TransIP

add_ipv6_to_vps(vps_name, ipv6_address)¶: Add Ipv6 Address to Vps

add_vps_to_private_network(vps_name, private_network_name)¶: Add VPS to a private Network

cancel_addon(vps_name, addon_name)¶: Cancel a Vps Addon

cancel_private_network(private_network_name, end_time)¶: Cancel a PrivateNetwork

cancel_vps(vps_name, end_time)¶: Cancel a Vps

clone_vps(vps_name)¶: Clone a VPS

clone_vps_to_availability_zone(vps_name, availability_zone)¶: Clone a VPS to a availability zone

create_snapshot(vps_name, description)¶: Create a snapshot

get_active_addons_for_vps(vps_name)¶: Get all the Active Addons for Vps

get_all_ips()¶: Get All ips

get_all_private_networks()¶: Get all Private networks in your account

get_available_addons()¶: Get available VPS addons

get_available_addons_for_vps(vps_name)¶: Get available Addons for Vps

get_available_availability_zones()¶: Get available availability zones

get_available_products()¶: Get available VPS products

get_available_upgrades(vps_name)¶: Get available VPS upgrades for a specific Vps

get_cancellable_addons_for_vps(vps_name)¶: Get cancellable addons for specific Vps

get_ips_for_vps(vps_name)¶: Get Ips for a specific Vps

get_operating_systems()¶: Get all operating systems

get_private_networks_by_vps(vps_name)¶: Get Private networks for a specific vps

get_snapshots_by_vps(vps_name)¶: Get all Snapshots for a vps

get_vps(vps_name)¶: Get a Vps by name

get_vps_backups_by_vps(vps_name)¶: Get all VpsBackups for a vps

get_vpses()¶: Get all Vpses

handover_vps(vps_name, target_accountname)¶: Handover a VPS to another TransIP User

install_operating_system(vps_name, operating_system_name, hostname)¶: Install an operating system on a vps

install_unattended(vps_name, operating_system_name, base64_install_text)¶: Install an operating system on a vps with a unattended installfile

order_addon(vps_name, addons)¶: Order addons to a VPS

order_private_network()¶: Order a private Network

order_vps(product_name, addons, operating_system_name, hostname)¶: Order a VPS with optional Addons

order_vps_in_availability_zone(product_name, addons, operating_system_name, hostname, availability_zone)¶: Order a VPS with optional Addons in a availability zone

remove_snapshot(vps_name, snapshot_name)¶: Remove a snapshot

remove_vps_from_private_network(vps_name, private_network_name)¶: Remove VPS from a private Network

reset(vps_name)¶: Reset a Vps

revert_snapshot(vps_name, snapshot_name)¶: Revert a snapshot

revert_snapshot_to_other_vps(sourcevps_name, snapshot_name, destinationvps_name)¶: Revert a snapshot to another VPS

revert_vps_backup(vps_name, backup_id)¶: Revert a vps backup

set_customer_lock(vps_name, enabled)¶: Enable or Disable a Customer Lock for a Vps

start(vps_name)¶: Start a Vps

stop(vps_name)¶: Stop a Vps

upgrade_vps(vps_name, upgrade_name)¶: upgrade a Vps

class transip.service.webhosting.WebhostingService(*args, **kwargs)¶

Transip_WebhostingService

create_mail_forward(domain, mailforward)¶: Transip_WebhostingService::createMailForward

create_mailbox(domain, mailbox)¶: Transip_WebhostingService::createMailBox

delete_mail_forward(domain, mailforward)¶: Transip_WebhostingService::deleteMailForward

delete_mailbox(domain, mailbox)¶: Transip_WebhostingService::deleteMailBox

get_available_packages()¶: Transip_WebhostingService::getAvailablePackages

get_available_upgrades(domain)¶: Transip_WebhostingService::getAvailableUpgrades

get_info(domain)¶: Transip_WebhostingService::getInfo

get_webhosting_domain_names()¶: Transip_WebhostingService::getWebhostingDomainNames

set_mailbox_password(domain, mailbox, password)¶: Transip_WebhostingService::setMailBoxPassword

update_mail_forward(domain, mailforward)¶: Transip_WebhostingService::modifyMailForward

update_mailbox(domain, mailbox)¶: Transip_WebhostingService::modifyMailBox

Objects¶

class transip.service.objects.DnsEntry(name, expire, record_type, content)¶: Representation of a DNS record as expected by the API

class transip.service.objects.Domain(name)¶: Transip_Domain

class transip.service.objects.Nameserver(hostname, ipv4=None, ipv6=None)¶: Transip_Nameserver

class transip.service.objects.WhoisContact¶: Transip_WhoisContact representation

class transip.service.objects.DomainBranding¶: Transip_DomainBranding

class transip.service.objects.WebhostingPackage(name, description, price, renewalPrice)¶: Transip_WebhostingPackage representation

class transip.service.objects.WebHost(domainName)¶: Transip_WebHost representation

class transip.service.objects.MailBox(address, maxDiskUsage=20)¶: Transip_MailBox representation

class transip.service.objects.MailForward(name, targetAddress)¶: Transip_MailForward representation

class transip.service.objects.Tld(name)¶: Transip_Tld representation

class transip.service.objects.DomainAction(name, hasFailed, message)¶: Transip_DomainAction representation

class transip.service.objects.WhoisContact: Transip_WhoisContact representation

class transip.service.objects.DomainCheckResult(domainName, status, actions)¶: Transip_DomainCheckResult representation

Miscellaneous Pages¶

Contribute¶

This project uses git & python.

Setup¶

In order to contribute, please start by making your own fork of this repository, and proceed to clone your own nifty fork to your local machine.

Isolating the Python environment with virtualenv is recommended. Use the following commands to set up a development environment within the Git workspace:

$ virtualenv .
$ . bin/activate
(transip-api) $ pip install -r dev_requirements.txt

Or by using virtualenvwrapper:

$ mkvirtualenv transip-api
$ cd /path/to/clone
$ setvirtualenvproject

Proceed to using pip to install all the dependencies

$ pip install -r dev_requirements.txt

Pull-Request¶

Please make sure that you make a separate branch for the changes you propose. Subsequent commits to the same branch as the Pull-Request originated from will be picked up by GitHub and added to the Pull-Request.

This is quite handy to change things when there are comments about the changeset, but can be annoying if not taken into account. If you make a Pull- Request from your develop branch and you continue developing, all new commits get added to the Pull-Request, which is clearly not wanted.

Testing & Code-quality¶

This project uses unittest to automatically test the software. Every Pull Request should contain tests, unless it is clear why they are not needed. (e.g. document change only, changes that don’t change behaviour.)

To ensure consistent code, pylint has been enabled for this project. Included is a .pylintrc file, with configuration for this project.

To run tests & pylint you can run these two commands

$ nosetests --rednose --with-coverage --cover-package=transip
$ pylint --rcfile=.pylintrc transip

Note

pylint configuration is not set in stone. Change the configuration if you feel the need to do so. Please do explain the reason for changing the configuration in the Pull-Request.

Warning

Bugfixes should add a test that fails with the bug unfixed, but passes with the bux fixed.

TravisCI¶

When a Pull-Request is made, TravisCI will automatically pick it up and test it using the settings from .travis.yml. The results will be made available both on GitHub with the Pull-Request, as on the specific page for this repository at TravisCI: https://travis-ci.org/mhogerheijde/transip-api. If anything fails, you can see the specifics about the failure there.

Obviously, Pull-Request that fail the test will not be merged.

License¶

Transip-api is licensed under a MIT License.

License Text¶

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.