Webbynode API Guide RC2

This guide is based on version RC1 of the Webbynode API. During this guide we will discuss three different areas that this version provides:

basic Client information access;
Webby actions and status;
DNS Zones and Records maintenance.

API Access Guidelines

Each API request should be done in the following format (curl is used here for illustration purposes, but any HTTPS compliant tool can be used):

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/[format]/[module][[/opt1]..[/optN]]

The accepted formats are xml, yaml and json.

Client Information Access

This is a very straightforward way to get information about the client account:

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/xml/client

Would return something similar to:

 1 <?xml version="1.0" encoding="UTF-8"?>
 2 <hash>
 3   <client>
 4     <status>Active</status>
 5     <city>My City</city>
 6     <address1>145 Wow Street</address1>
 7     <companyname>Webbynode</companyname>
 8     <postcode>9090010</postcode>
 9     <credit type="decimal">10.0</credit>
10     <country>US</country>
11     <phonenumber>555-1902</phonenumber>
12     <lastname>Coury</lastname>
13     <firstname>Felipe</firstname>
14     <datecreated type="date">2008-11-16</datecreated>
15     <state>SP</state>
16     <email>felipe@webbynode.com</email>
17   </client>
18 </hash>

Of course you can use JSON or YAML, with similar results:

 1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
 2   https://manager.webbynode.com/api/xml/client | jsonpretty
 3 
 4 {
 5   "client": {
 6     "address1": "145 Wow Street",
 7     "city": "My City",
 8     "status": "Active",
 9     "companyname": "Webbynode",
10     "postcode": "9090010",
11     "credit": 10.0,
12     "country": "US",
13     "firstname": "Felipe",
14     "lastname": "Coury",
15     "phonenumber": "555-1902",
16     "datecreated": "2008-11-16",
17     "email": "fcoury@me.com",
18     "state": "SP"
19   }
20 }
21 
22 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
23   https://manager.webbynode.com/api/yaml/client
24 
25  ---
26   client:
27     status: Active
28     city: My City
29     address1: 145 Wow Street
30     companyname: Webbynode
31     postcode: "9090010"
32     credit: 10.0
33     country: US
34     phonenumber: 555-1902
35     lastname: Coury
36     firstname: Felipe
37     datecreated: 2008-11-16
38     state: SP
39     email: fcoury@me.com

Webbies Management

My Webbies

1 https://manager.webbynode.com/api/xml/webbies

Data returned for each Webby:

name
plan
ip
node
notes
status

You can get a list of all Webbies under your account (or get the “My Webbies” list). As an example, you can do:

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/xml/webbies

And get a list of your Webbies in the following format:

 1 <?xml version="1.0" encoding="UTF-8"?>
 2 <hash>
 3   <webbies type="array">
 4     <webby>
 5       <ip>208.0.0.30</ip>
 6       <status>Redeploying</status>
 7       <name>sandbox</name>
 8       <notes>my sandbox</notes>
 9       <plan>Webby_256</plan>
10       <node>miami-a02</node>
11     </webby>
12     <webby>
13       <ip>208.64.71.27</ip>
14       <status>on</status>
15       <name>hasmany.info</name>
16       <notes nil="true"></notes>
17       <plan>Webby_384</plan>
18       <node>miami-a04</node>
19     </webby>
20   </webbies>
21 </hash>

Executing Webby actions

1 https://manager.webbynode.com/api/xml/webby/:hostname/:action

In a similar way, you can also execute actions on your Webbies using the API. The current actions are start, shutdown and reboot. Aside from those, you can also ask for Webby status. Let’s play with a Webby as an example:

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/xml/webby/webby555/status
3 <?xml version="1.0" encoding="UTF-8"?>
4 <hash>
5   <status>off</status>
6 </hash>

As you can see, the webby is off. Let’s start it:

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/xml/webby/webby555/start
3 <?xml version="1.0" encoding="UTF-8"?>
4 <hash>
5   <job-id type="integer">1044</job-id>
6 </hash>

The job-id indicates that the starting job was scheduled to run. In future releases of the API we’ll be able to poll a given Job Id for status. In this version, you have to take a look at the status of the Webby again:

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/xml/webby/webby555/status
3 <?xml version="1.0" encoding="UTF-8"?>
4 <hash>
5   <status>on</status>
6 </hash>

As you can see, it is on. So let’s reboot it now:

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/xml/webby/webby555/reboot
3 <hash>
4   <job-id type="integer">1045</job-id>
5 </hash>

If we quickly run a status, right after submitting the reboot command, we’ll have something like this:

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/xml/webby/webby555/status
3 <?xml version="1.0" encoding="UTF-8"?>
4 <hash>
5   <status>Rebooting</status>
6 </hash>

Eventually, when rebooting completes we’ll be back to “on” status. So, to wrap this up, let’s shut it down:

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/xml/webby/webby555/shutdown
3 <?xml version="1.0" encoding="UTF-8"?>
4 <hash>
5   <job-id type="integer">1046</job-id>
6 </hash>

DNS management

The final feature of this first version of the API is DNS management. You can add, update and remove DNS Zones and Records using this API area. Here is a summary of the commands:

List all DNS zones

1 https://manager.webbynode.com/api/xml/dns

Data returned for each DNS zone:

id
domain
status
ttl

Example:

 1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
 2   https://manager.webbynode.com/api/xml/dns
 3 <?xml version="1.0" encoding="UTF-8"?>
 4 <hash>
 5   <zones type="array">
 6     <zone>
 7       <domain>agreatdomain.com.</domain>
 8       <status>Active</status>
 9       <id type="integer">14</id>
10       <ttl type="integer">86400</ttl>
11     </zone>
12     <zone>
13       <domain>awesomedomain.net.</domain>
14       <status>Active</status>
15       <id type="integer">48</id>
16       <ttl type="integer">86400</ttl>
17     </zone>
18   </zones>
19 </hash>

Fetch information about a given zone (by passing its id)

1 https://manager.webbynode.com/api/xml/dns/:id

Data returned:

id
domain
status
ttl

Example:

 1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
 2   https://manager.webbynode.com/api/xml/dns/14
 3 <?xml version="1.0" encoding="UTF-8"?>
 4 <hash>
 5   <zone>
 6     <domain>agreatdomain.com.</domain>
 7     <status>Active</status>
 8     <id type="integer">14</id>
 9     <ttl type="integer">86400</ttl>
10   </zone>
11 </hash>

Fetch records for a given DNS zone (using zone id)

1 https://manager.webbynode.com/api/xml/dns/:id/records

Data returned:

id
type
name
data
aux
ttl

Example:

 1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
 2   https://manager.webbynode.com/api/xml/dns/14/records
 3 <?xml version="1.0" encoding="UTF-8"?>
 4 <hash>
 5   <records type="array">
 6     <record>
 7       <type>A</type>
 8       <aux type="integer">0</aux>
 9       <name></name>
10       <data>200.100.200.100</data>
11       <id type="integer">51</id>
12       <ttl type="integer">86400</ttl>
13     </record>
14     <record>
15       <type>A</type>
16       <aux type="integer">0</aux>
17       <name>*</name>
18       <data>200.100.200.100</data>
19       <id type="integer">26</id>
20       <ttl type="integer">86400</ttl>
21     </record>
22   </records>
23 </hash>

DNS Zone management

Adding new zones:

1 https://manager.webbynode.com/api/xml/dns/new

Get or update information about a given zone:

1 https://manager.webbynode.com/api/xml/dns/:id

Delete records:

1 https://manager.webbynode.com/api/xml/dns/:id/delete

Parameters (* = required)

zone[id]
zone[domain]*
zone[ttl]*
zone[status]=Active | Inactive

Examples:

 1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
 2   https://manager.webbynode.com/api/xml/dns/new
 3   -F "zone[domain]=sweetnewdomain.com" -F "zone[ttl]=86400"
 4 <?xml version="1.0" encoding="UTF-8"?>
 5 <hash>
 6   <domain>sweetnewdomain.com.</domain>
 7   <status>Active</status>
 8   <id type="integer">50</id>
 9   <ttl type="integer">86400</ttl>
10 </hash>

Please note that we add the trailing “.” to a domain to make it comply with how DNS works. But you can add it yourself:

 1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
 2   https://manager.webbynode.com/api/xml/dns/new
 3   -F "zone[domain]=thisalreadyendswithadot.com." -F "zone[ttl]=86400"
 4 <?xml version="1.0" encoding="UTF-8"?>
 5 <hash>
 6   <domain>thisalreadyendswithadot.com.</domain>
 7   <status>Active</status>
 8   <id type="integer">51</id>
 9   <ttl type="integer">86400</ttl>
10 </hash>

We also do content validation:

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/xml/dns/new
3   -F "zone[domain]=invaliddomain.com." -F "zone[ttl]=invalid-value"
4 <?xml version="1.0" encoding="UTF-8"?>
5 <hash>
6   <errors>ttl is not a number</errors>
7 </hash>

And check if all the mandatory parameters are present:

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/xml/dns/new
3   -F "zone[ttl]=86400"
4 <?xml version="1.0" encoding="UTF-8"?>
5 <hash>
6   <errors>domain can't be blank</errors>
7 </hash>

For fetching information about a given zone, we do:

 1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
 2   https://manager.webbynode.com/api/xml/dns/51
 3 <?xml version="1.0" encoding="UTF-8"?>
 4 <hash>
 5   <zone>
 6     <domain>thisalreadyendswithadot.com.</domain>
 7     <status>Active</status>
 8     <id type="integer">51</id>
 9     <ttl type="integer">86400</ttl>
10   </zone>
11 </hash>

And to update, we do the very same thing, passing the parameters we want to change:

 1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
 2   https://manager.webbynode.com/api/xml/dns/51
 3   -F "zone[status]=Inactive"
 4 <?xml version="1.0" encoding="UTF-8"?>
 5 <hash>
 6   <domain>thisalreadyendswithadot.com.</domain>
 7   <status>Inactive</status>
 8   <id type="integer">51</id>
 9   <ttl type="integer">86400</ttl>
10 </hash>

And finally, to delete a zone:

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/xml/dns/51/delete
3 <?xml version="1.0" encoding="UTF-8"?>
4 <hash>
5   <success type="boolean">true</success>
6 </hash>

DNS Record management

Adding new records:

1 https://manager.webbynode.com/api/xml/dns/:id/records/new

Get or update information about one record:

1 https://manager.webbynode.com/api/xml/records/:id

Delete records:

1 https://manager.webbynode.com/api/xml/records/:id/delete

Parameters (* = required)

record[id]
record[type]*
record[name]
record[data]*
record[aux]
record[ttl]

Examples:

In the beginning, we don’t have any records:

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/xml/dns/50/records
3 <?xml version="1.0" encoding="UTF-8"?>
4 <hash>
5   <records type="array"/>
6 </hash>

So let’s add one:

 1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
 2   https://manager.webbynode.com/api/xml/dns/50/records/new
 3   -F "record[type]=A" -F "record[data]=200.100.200.100"
 4 <?xml version="1.0" encoding="UTF-8"?>
 5 <hash>
 6 <record>
 7   <type>A</type>
 8   <aux type="integer">0</aux>
 9   <name></name>
10   <data>200.100.200.100</data>
11   <id type="integer">116</id>
12   <ttl type="integer">86400</ttl>
13 </record>
14 </hash>

And then let’s fetch information about this record we just added:

 1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
 2   https://manager.webbynode.com/api/xml/records/116
 3 <?xml version="1.0" encoding="UTF-8"?>
 4 <hash>
 5   <record>
 6     <type>A</type>
 7     <aux type="integer">0</aux>
 8     <name></name>
 9     <data>200.100.200.100</data>
10     <id type="integer">116</id>
11     <ttl type="integer">86400</ttl>
12   </record>
13 </hash>

Please note that we don’t need to use the /dns/:id part, because once you have the record id, it doesn’t matter to which DNS zone it belongs.

Also, the same URL used for fetching information about a given record can receive parameters to update the record, like this:

 1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
 2   https://manager.webbynode.com/api/xml/records/116
 3   -F "record[data]=100.200.0.110"
 4 <?xml version="1.0" encoding="UTF-8"?>
 5 <hash>
 6   <record>
 7     <type>A</type>
 8     <aux type="integer">0</aux>
 9     <name></name>
10     <data>100.200.0.110</data>
11     <id type="integer">116</id>
12     <ttl type="integer">86400</ttl>
13   </record>
14 </hash>

Finally, you can delete a record by using:

1 curl -F "email=myemail@example.com" -F "token=mytokengoeshere"
2   https://manager.webbynode.com/api/xml/records/116/delete
3 <?xml version="1.0" encoding="UTF-8"?>
4 <hash>
5   <success type="boolean">true</success>
6 </hash>

Comments