Developer API Documentation

Introduction

We have begun developing an API that provides access to our data. This will allow you to retrieve items such as bandwidth or disk usage for use in scripts, IRC bots, or whatever ideas you can dream up. Being in such an early stage of development the interface may change as we prototype; if you do begin using the interface please let us know, we're eager to see what you can come up with.

The API is built on top of the HTTP protocol offering a REST interface. Requests are made by sending a GET or POST command with the former being used to retrieve data and the latter for world state changes; for example an FAQ search query would be GET, however requesting a bandwidth check would use POST. When to use either is clearly documented in our reference documentation and comes complete with examples. Once a command has been sent, our servers will return an appropriate response in JSON format. By keeping to existing standards, most example links should work straight from your browser after logging in. You can see the interface in play right now (make sure to be logged in): search for the FAQ licence. How simple was that?

One caveat is that you will need a working slot with us for the API to be useful for you. Your application will also need to work with user granted "permissions" so that people can authorise another user to access a limited part of their account data—you will also need to provide accurate descriptions and fallback in functionality where possible if the user decides to grant only some of the permissions requested.

Authentication and Authorisation

There are multiple methods to use the API, the first and easiest is to re-use cookies from your browser session. Simply login to the website and you will have full access to your user data on the API, however any other users that have granted your application access will not be available when this mode is used. Next is via HTTP basic access authentication using API keys specially generated for your application (e.g. "https://username:password@www.feralhosting.com/"), this is the ideal method and grants full access to data from other users who have permitted it.

Access and the state of the request should be checked by looking at the status code returned, all requests are done over HTTPS. Below shows the status code and the meaning:

  • 200 OK—everything is okay and the page returned successfully.
  • 401 Unauthorized—the client login was unsuccessful or details were not provided.
  • 403 Forbidden—the client does not have sufficient permission to view the page, e.g. the user has not granted access.
  • 404 Not Found—the requested page or protocol was not found.

Before being able to fetch data on behalf of users you will first need to get permission from them, when you create an application you will be given a unique URL which can be passed to users. Please be careful about presenting and transferring user data over unecrypted channels.

Anatomy of a Request

Each request's URL is made up of the following format: https://www.feralhosting.com/api/json/protocol/username/page/?query

The emphasised parts of the string are parameters expected to be provided by your application they can and will vary from request to request (potentially even the protocol version). Below is a synopsis of the parameters expected

  • protocol—a string representing the target API version requested. More information about what is in each protocol version is available.
  • username—an optional string specifying the user to execute this resource as. If omitted it defaults to your own username, if included the specified user must have granted access to the page to your application; if you specify your own username here, you will also need to grant permissions in the same any other user would.
  • page—a string specifying the specific resource to handle the request. A complete reference with examples is also available.
  • query—a query string made up of name / value pairs separated with an ampersand & suffix. These are used to specify parameters into the page and are specified further by the reference.

All responses from the API will return a JSON formatted string with the following elements:

{
    "error": [
        "This is a showstopper of an error message.",
        "You cannot enter a negative number."
    ],
    "warning": [
        "I warn thee, do not proceed."
    ],
    "meta": {
        "server" => "scarlet.feralhosting.com",
        "protocol" => "123.456c",
        "page" => "path/to/page",
        "username" => "Joshua",
    },
    "response": {
        ...
    }
}

The JSON document returned is made up of four parts: error, warning, meta, and response. Each are desribed below:

  • error—the error key is consists of an array of strings each representing an error returned by the page. All errors are fatal and receiving one will result in the response key not being present.
  • warning—this key works similar to an error however it reports non-fatal problems with the request and the page continues to be processed.
  • meta—this represents information about the request and how it was seen by the API. The protocol, page, and username keys all correspond to the values passed via the HTTP request, if no username was specified the username the request was made as is returned; the server key identifies the hostname of the server that responded and may differ depending on the request.
  • response—this contains the mainstay of the reply and will differ depending on the page and is documented in the reference pages.

Both the warning and error message text generated can be safely presented to the end-user.

Terminology

The API documentation refers to terms that are not found on the website, they instead follow what's used in the source code and database powering them underneath. This leads to a much more stable set of terms but misunderstandings can arise if this is the case. For example, all slots, dedicated servers, and other services purchased are known as "account plans" and differ by the "plan" given to them. Below is a list of commonly used terms that may not be so obvious:

Account Plan
Represents a service purchased at Feral Hosting and translates into a slot, dedicated server, and more.
Plan
A description of a service that can (or could) be purchased by a customer.
Period
A start and possibly a NULL end date associated with a cost.

Further Reading

That's it! There isn't much more to say—so get going! You can find the list of pages along with their functionality, input, and output on the references pages. Remember, we'd love to hear what you come up with.