This API method has two uses:
- Listing hosts that belong to a specific zone
- Searching for hosts the belong to any zone or a specific zone
Request
Example
GET /api/1.1/zones/12345678/hosts.xml
GET /api/1.1/zones/12345678/hosts.xml?per_page=10&page=2
GET /api/1.1/hosts.xml?zone_id=12345678
GET /api/1.1/zones/12345678/hosts.xml?fqdn=www.example.com
GET /api/1.1/hosts.xml?fqdn=www.example.comNotes
There are two optional parameters: page=# and per_page=#. page defaults to 1 (and starts at 1, not 0). per_page defaults to 100 but should be specified exactly if a change of the default value will cause your application to fail. The maximum value for per_page is 1000.
It is possible to search by hostname to limit the result set. Searches are based on the FQDN (fully qualified domain name) which is the combination of the hostname (if any) and the zone/domain name.
If the FQDN matches the zone’s domain exactly, then the search will be for records with a hostname of nil.
Response
Example header
X-Query-Count: 12Example body
<hosts type="array">
<host>
<created-at type="datetime">2008-12-07T02:51:13Z</created-at>
<data>172.16.16.1</data>
<fqdn>example.com</fqdn>
<host-type>A</host-type>
<hostname nil="true"/>
<id type="integer">23456789</id>
<notes nil="true"/>
<priority type="integer" nil="true"/>
<ttl type="integer" nil="true"/>
<updated-at type="datetime">2008-12-07T02:51:13Z</updated-at>
<zone-id type="integer">12345678</zone-id>
</host>
</hosts>Notes
X-Query-Count will contain the total number of results, including those that didn’t fit inside this response. For example, if there are 12 results and per_page (above) is 10, only 10 entries will be returned but X-Query-Count will show 12 so that you know there are more results remaining.