API documentation

This document describes how to use the API.

Output formats

You can specify an output format by using the format request parameter. If you do not specify a format, json will be used:
    /api/?format=json
The following formats are currently supported:
FormatExplanation
jsonJSON
services.xmlXML, based on the Service Discovery Protocol format.
services-full.xmlA more descriptive XML format, compatible with the one from xmpp.org.
Other formats (generic XML, possibly others) will be supported once I have the time.

Filter by country

You can filter servers by countries by giving the country request parameter:
    /api/?country=at
There is no really reliable way of determining the server a country is in. The country is determined by the coordinates the server-admin gives when registering the server (and they in turn are not in any way verified).

Require features

You can limit the output to servers that have a certain feature. To do that, simply give the features request parameter:
    /api/?features=tls,ipv6
The following features are currently recognized:
FeatureExplanation
plainServers that allow plain, unencrypted connections.
sslServers that allow connections via SSL.
tlsServers that allow connections via TLS.
ipv6Servers that have IPv6 connectivity.
Note: Currently only IPv6 is actually verified, all other features will always return an empty list.

Output additional fields

By default, The API outputs only a list of JIDs. You can request more fields via the fields request parameter:
    /api/?fields=website,ca
Currently the following fields are supported:
FieldExplanation
launchedWhen the server was launched.
locationWhere the server is located.
websiteThe website of the server.
caThe Certificate Autority of the server.
softwareThe software this server uses.
software_versionThe version of the software the server uses.
contactThe contact address of this server.
Note: The output of this feature is still subject to change.
Note: The fields parameter is ignored when using format=services.xml or format=services-full.xml.