BuddyNS API

BuddyNS offers a simple, powerful API to all users. This API allows you to:

  • Manage the zones associated with your account (list, add, remove)
  • Verify the correctness and health of a zone's delegation (registry, authority)
  • Check the state of a zone on the BuddyNS cluster (serial, time of refresh et al.)
  • Request immediate synchronization of a zone (SyncNOW)

Terms of Use & feedback

APIv1 was open to Paid Users only. APIv2 is accessible to all BuddyNS users. According to our GToU, we retain rights to revoke access individually (e.g. upon resource abuse).

You need a BuddyNS user account to use the API. To get one, activate a zone on BuddyNS.

For any comment or idea, our feedback address is always open. Just drop us an e-mail!

Quick links

Python client

Easily drive BuddyNS from python code. Integrate BuddyNS in your system within minutes, using a simple programmatic interface.

View on PyPI →

Interactive docs

Discover the API by clicking your way through resources; see example snippets and generate client code automatically.

View on SwaggerHub →

Choose your API documentation type

You can browse documentation of BuddyNS' API in two flavors:

  • For a quickstart, read the remainder of this page. Basic principles, resources, and right into examples.
  • For a complete, interactive reference, follow to our Interactive documentation →

You may also download our OpenAPI specification.

When using the interactive API, beware of the following:

  • You can perform interactive queries against BuddyNS' live API. Press "Authorize" and enter Token 1d313d98067f95c0b1e899a6528573c65d67bc7c (replace the hash with your own token). Entering the bare token without the "Token " prefix will not work.
  • POST operations may contain fields marked as read-only. This is a bug of Swagger, the tool powering the interactive page from our OpenAPI specification.
  • Several resources return Hypermedia links to others, which may not be mentioned in the OpenAPI specification for simplicity.

Technical overview

We display examples using the curl command-line HTTP browser for simplicity. Obviously all queries are applicable to any alternative client (wget, python, ruby, PHP etc).

Compatibility note

This is major version v2 of the API. Within v2, new fields can be introduced in responses; existing fields and paths will not be modified.

Security and Authentication

Access methods:

  • HTTP
  • HTTPs

and we highly recommend you use HTTPs.

The API exclusively provides user-specific data. The user is authenticated with any of these mechanisms:

  • Basic HTTP authentication (for external tools)
  • API Key / Token

API Key

The API key allows every API operation (including removing zones, or changing their master) without entering the original username + password.

Use this when you need to store your API access data anywhere that could be compromised. If compromised, your original username and password remain safe. For security reasons, API Key access is disabled by default.

You can enable API Key access from your BuddyBoard. If you do, protect your API Key like a password. For the same reasons, we allow key-based API access only over HTTPs. Once enabled, Token-based authentication is performed by passing special HTTP header Authorization: Token X to the request, where X is your token as provided by the BuddyBoard.

Authentication examples

Access with Basic Authentication, when username is user@domain.com and password mypassword:

curl -u user@domain.com:mypassword -XGET https://www.buddyns.com/api/v2/zone/

Access with API Key / Token authentication, when token is 25719b77324162b3f369f27db37f41bbb5de6bd5:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XGET https://www.buddyns.com/api/v2/zone/

Rate limits

The API is protected by rate limits at multiple levels to ensure uptime and fair access to all users. Make sure your scripts avoid fast-rate bulks of requests at once, and large overall number of requests over a longer time span.

Field Syntactic type Semantic type
Domain / Zone name UTF-8 String RFC 3490 or IDNA
Timestamp ISO 8601 String UTC timezone
Master & Address String IPv4 or IPv6
Mobile number String ITU-T E.123

Formats & types

All request parameters are passed in standard HTTP POST format.

All responses are given in JSON format.

Types are as listed in the table.

Model and paths

The API follows the RESTful architecture, and implements Hypermedia — the highest maturity level of Richardson's REST Maturity Model.

The following resources are available, with common base URL https://www.buddyns.com/api/v2/:

URL GET POST PUT DELETE
/api/v2/zone/ List all zones Add a new zone. Mandatory arguments: none none
/api/v2/zone/myzone.com Get configuration details:
  • name RFC 3490
  • name_idn
  • serial
  • master
  • creation_ts
 none none Delete zone
/api/v2/zone/myzone.com/status/ Get status details:
  • zone RFC 3490
  • transfer_ok
  • first_failure_ts
  • last_failure_ts
  • last_success_ts
 none none none
/api/v2/zone/myzone.com/delegation/ Get delegation details:
  • registry_ok
  • authority_ok
  • master_ok
 none none none

Sync is a virtual resource to request SyncNOW!, that is immediate synchronization of one o more zones.

URL GET POST PUT DELETE
/api/v2/sync/ SyncNOW all zones in account none none none
/api/v2/sync/myzone.com SyncNOW myzone.com only none none none
URL GET POST PUT DELETE
/api/v2/user/ Get essential user parameters:
  • email
 none none none
/api/v2/user/profile/ Get profile parameters:
  • used_traffic
  • estimated_traffic
  • mobile_number ITU-T E.123
  • cpanel_integration
 none Change parameters: none
URL GET POST PUT DELETE
/api/v2/service/ Get service parameters:
  • account_type
  • num_zones
  • traffic_quota
  • num_stats
 none none none

Internationalized Domain Names

BuddyNS pioneers support for Internationalized Domain Names (those with funny characters in them). No less, this API is fully IDN-capable.

IDN names can be passed in both their UTF and ASCII forms, and this applies to both parameters and URLs.

Responses normally contain their original (end-user, UTF) representation; when details are responded, the canonical (ASCII-encoded) representation is also included.

BuddyNS is cool full-stack.

Learn by example

Create zone

Activate new zone microsoft.com (master 65.55.37.62) in account user@domain.com:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XPOST -F "name=microsoft.com" -F "master=65.55.37.62" https://www.buddyns.com/api/v2/zone/

This returns the newly added zone:

{"name": "microsoft.com", "name_idn": "microsoft.com", "serial": null, "master": "65.55.37.62", "creation_ts": "2013-11-06T19:39:38.205"}

List zones

Fetch the list of zones for account user@domain.com:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XGET https://www.buddyns.com/api/v2/zone/

Will respond with an array of objects:

[ {
    "name" : "microsoft.com",
    "name_idn" : "microsoft.com",
    "creation_ts" : "2013-11-06T19:39:38.205",
    "master" : "65.55.37.62",
    "serial" : 2013110601,
    "status": "/api/v2/zone/microsoft.com/status/",
    "delegation": "/api/v2/zone/microsoft.com/delegation/"
},
{
    "name" : "bücher.de",
    "name_idn" : "xn--bcher-kva.de",
    "creation_ts" : "2012-06-06T19:53:07.269",
    "master" : "154.15.200.6",
    "serial" : 1383743519,
    "status": "/api/v2/zone/bücher.de/status/",
    "delegation": "/api/v2/zone/bücher.de/delegation/"
 } ]

Removing a zone

Use the DELETE method on the zone:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XDELETE https://www.buddyns.com/api/v2/zone/myzone.com

This return no content on success. On failure, you get this error:

{"detail": "Not found"}

Updating a zone's parameters

Implement this with a chained call: delete the zone and re-add it with the new data.

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XDELETE https://www.buddyns.com/api/v2/zone/myzone.com
curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XPOST -F "name=myzone.com" -F "master=4.3.2.1" https://www.buddyns.com/api/v2/zone/

Getting zone config details

Use the /status/ URL specifier on the zone resource:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XGET https://www.buddyns.com/api/v2/zone/b%C3%BCcher.de/status/

The response:

{"zone": "xn--bcher-kva.de", "transfer_ok": true, "first_failure_ts": "2013-08-20T14:36:31.808", "last_failure_ts": "2013-08-20T14:36:31.808", "last_success_ts": "2013-11-07T21:59:15.581"}

Getting zone delegation details

Use the /delegation/ URL specifier on the zone resource:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XGET https://www.buddyns.com/api/v2/zone/b%C3%BCcher.de/delegation/

The response:

{"zone": "bücher.de", "master": "154.15.200.6", "master_ok": true, "registry_ok": true, "authority_ok": true}

SyncNOW a zone

Use the /api/v2/sync/b%C3%BCcher.de URL specifier on the syncnow resource:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XGET https://www.buddyns.com/api/v2/sync/b%C3%BCcher.de

On success the response has empty content.

Getting amount of traffic consumed

Simply GET the /user/profile/ resource:

curl -H "Authorization: Token 25719b77324162b3f369f27db37f41bbb5de6bd5" -XGET https://www.buddyns.com/api/v2/user/profile/