Installation¶
If you haven’t already, start by installing it with pip:
pip install --upgrade pynamecom
Quick Start¶
Use DnsApi to create a dns record:
from namecom import Auth, DnsApi
auth = Auth('username', 'access_token')
api = DnsApi(domainName='example.org', auth=auth)
result = api.create_record(host='test', type='A', answer='10.0.0.1')
To access the service, an access token is required. You could find or generate one at API Token Manage Page:
>>> from namecom import Auth
>>> auth = Auth('username', 'access_token')
When created, an api class accepts the Auth instance and use it to do the authentication:
>>> from namecom import DnsApi
>>> api = DnsApi(domainName='example.org', auth=auth)
Let’s find out how to create a dns record using python’s built-in help:
>>> help(DnsApi)
class DnsApi(_ApiBase)
| The api class for DNS. More details about each parameter :class:`here <namecom.Record>`.
| Official namecom documentation : https://www.name.com/api-docs/DNS
| ...
| create_record(self, host, type, answer, ttl=300, priority=None)
| Creates a new record in the zone.
|
| Parameters
| ----------
| host : string
| hostname relative to the zone
| type : string
| dns record type
| answer : string
| dns record answer
| ttl : int
| dns record ttl
| priority : int
| dns record priority
|
| Returns
| -------
| :class:`~namecom.result_models.CreateRecordResult`
| a response result instance with parsed response info
You can also see the API Reference for more details. Now let’s try this method:
>>> result = api.create_record(host='test', type='A', answer='10.0.0.1')
The result of api calls are strongly typed by result models. From the docstring above we know it’s an instance of CreateRecordResult. Let’s see what’s in this class:
>>> help(namecom.result_models.CreateRecordResult)
class CreateRecordResult(RequestResult)
| Response class for CreateRecord method.
|
| Attributes
| ----------
| record : :class:`~namecom.Record`
| instance of Record
It has a record attribute of type Record which contains the parsed response information:
>>> result.record
Record(domainName='example.org', fqdn='test.example.org.', priority=None, host='test', ttl=300, answer='10.0.0.1', type='A', id=357756)
For most use cases, you can follow these steps to find out how to use it.
More About API¶
There are seven API in total:
And there are two types of model:
- Data Model - represent entities for name.com api, like domain, dns record and email forwarding.
- Result Model - represent api response, contains data models and other fields like nextPage and lastPage.
The name of api method and its params are almost identical to the official name.com documentation. When calling these methods, they will do the following things:
- construct and send request
- check response and throw error if necessary
- parse response into result model and return
More References¶
Usage Example¶
For more examples, test cases for the project illustrate how to interact with each api:
Hey, it’s not Snake Case!¶
As you may have already noticed, some parameters of api method and data model attributes are not snake case. I feel guilty if I don’t explain, so here are the reasons:
- For people who want to use name.com api, they should already have read the official api doc. Keeping the same name convention from official doc would made it more consistent and nature to use.
- Keeping names consistent with official api brings convenience when parsing response and building request.
And I feel even less guilty after reading PEP8:
mixedCase is allowed only in contexts where that’s already the prevailing style
