README.rst
1===========
2TransIP API
3===========
4
5|Build Status| |Docs Status|
6
7.. |Build Status| image:: https://travis-ci.org/benkonrath/transip-api.svg?branch=master
8 :target: https://travis-ci.org/benkonrath/transip-api
9 :alt: Build Status
10.. |Docs Status| image:: https://readthedocs.org/projects/transip-api/badge/?version=latest
11 :target: https://transip-api.readthedocs.io/en/latest/?badge=latest
12 :alt: Documentation Status
13
14This library aims to implement the `TransIP API`_ in Python.
15
16Quick Start
17===========
18
19Prerequisite
20------------
21
22* Make sure you have an account at TransIP_
23* *Enable* the API (https://www.transip.nl/cp/mijn-account/#api)
24* Whitelist your IP.
25* Generate a new key-pair.
26 + Copy-paste the private key into a file.
27 + Put the private key in a file called ``decrypted_key`` beside this ``README.rst`` file.
28
29Setup
30-----
31
32You can get the library directly from PyPi:
33
34.. code-block::
35
36 $ pip install transip
37
38Example
39-------
40
41The command-line interpreter doesn't do much yet. By default it does a
42getDomainNames() call, but with the '-u' option it's also possible to add or
43update DNS records. When calling it with '-h', it will show all available options.
44
45.. code-block::
46
47 $ transip-api
48 [example.com, example.org, example.net]
49
50 $ transip-api -h
51 usage: transip-api [-h] [-l LOGINNAME] [-s] [-a] [-u] [-d]
52 [--domain-name DOMAIN_NAME] [--entry-name ENTRY_NAME]
53 [--entry-expire ENTRY_EXPIRE] [--entry-type ENTRY_TYPE]
54 [--entry-content ENTRY_CONTENT] [--api-key PRIVATE_KEY_FILE]
55
56 optional arguments:
57 -h, --help show this help message and exit
58 -l LOGINNAME, --login-name LOGINNAME
59 TransIP username
60 -s, --show-dns-entries
61 show all DNS entries for a domain
62 -a, --add-dns-entry add an entry in the DNS
63 -u, --update-dns-entry
64 update an entry in the DNS
65 -d, --delete-dns-entry
66 delete an entry in the DNS
67 --domain-name DOMAIN_NAME
68 domain name to use
69 --entry-name ENTRY_NAME
70 name of the DNS entry
71 --entry-expire ENTRY_EXPIRE
72 expire time of the DNS entry
73 --entry-type ENTRY_TYPE
74 type of the DNS entry
75 --entry-content ENTRY_CONTENT
76 content of the DNS entry
77 --api-key PRIVATE_KEY_FILE
78 TransIP private key
79
80
81Example of adding/updating a record:
82
83.. code-block::
84
85 $ 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
86 Request finished successfully.
87
88
89Documentation
90=============
91
92Further documentation can be found in the ``docs`` directory, or on https://transip-api.readthedocs.io/en/latest/.
93
94.. _virtualenv: http://virtualenv.org/
95.. _TransIP: https://www.transip.nl/cp/
96.. _`TransIP API`: https://www.transip.eu/transip/api/
97
98FAQ
99===
100
101Question:
102
103 When using the library I get SSL errors such as:
104
105 .. code-block::
106
107 urllib2.URLError: <urlopen error [Errno 1] _ssl.c:510: error:14077458:SSL routines:SSL23_GET_SERVER_HELLO:tlsv1 unrecognized name>
108
109Answer:
110
111 The `suds` library has fairly limited SSL support which is dependent on the Python version, to work around this the `suds_requests` library can be used which replaces `urllib2` with the `requests` library. Additionally the `requests` library automatically pools connections which makes the library slightly faster to use.
112 To install:
113
114 .. code-block::
115
116 pip install suds_requests
117
