API Basics

This API is what is considered "RESTful". The HTTPS endpoint that you will need to talk to is https://www.portfast.co.uk/api. There will be libraries for any language that you want to use which can facilitate communication with this API, you can even use curl from the command line if you are so inclined.

This documentation is very much incomplete, we will continue to work on it.

The API key is like a persistent session, so there is no need to log in. This is why it is important to keep it secret, and to set the access list only to your trusted addresses.

We have already put the API key in a dot-file in our home directory to make it easier to use.

You can make the requests using any language, here is an example with curl. The responses are not pretty-printed so you might want to pipe it through something (in our examples we use jq) to make it more legible.

Node: /account

Query:

$ curl https://www.portfast.co.uk/api/account -s -H "X-Portfast-Key: $(cat ~/.portfast-key)" | jq
{
    "address": {
        "address1": "7 A Road",
        "address2": "",
        "city": "Sheffield",
        "country": "GB",
        "county": "",
        "postcode": "S7 2AA"
    },
    "admin": true,
    "email": {
        "email": "tom@example.com",
        "email2": "",
        "email2_offers": true,
        "email2_service": true,
        "email_googlemx": false,
        "email_offers": true,
        "email_service": true
    },
    "name": "Tom Bird",
    "organisation": "Portfast Ltd",
    "phone": {
        "fixed": "",
        "mobile": "+44.7911111117"
    },
    "suspended": false,
    "username": "tom",
    "uuid": "53d63966-1f4e-44e6-8639-30c00f720ba6"
}

Assuming you have permission, the system will respond with your user object.

Your IP address

As API keys are restricted by IP address and also it can be useful to know your address if you should want to dynamically set it, this end point returns only the address that you call it from. It's unauthenticated to aid with debugging.

Node: /ipaddress

Query:

$ curl -s https://www.portfast.co.uk/api/ipaddress | jq
{
  "address": "2001:db8::1701:d",
  "family": "ipv6"
}

API keys

You will need to generate an API key before you can use the API service. This is so that you aren't logging in with your usual username and password, and also for security it is IP address locked. You can generate it here.

Keep this key out of your version control system if you publish your code.

Services

These are your managed hosting products, for example DNS and web hosting.

Node: /service/list

This node lists your active services. You will receive an array of service objects. The most useful bit of data from this query is the UUID of the service, this allows you to manipulate it.

Response:

[
   {
      "product" : "DNS only",
      "expires" : "2015-10-25 01:41:42 +0100",
      "features" : {
         "www" : false,
         "dns" : true,
         "mysql" : false,
         "mail" : false
      },
      "quota" : {
         "domains_permitted" : 10,
         "domains_hosted" : 3
      },
      "active" : true,
      "epoch" : {
         "expires" : 1445733702
      },
      "uuid" : "67f65329-0dc3-4499-8522-86afc64df17d",
      "domains" : [
         "205.246.188.in-addr.arpa",
         "example.com",
         "example.net"
      ],
      "id" : 135,
      "configured" : true
   }
]

Node: /service/domain/add

Request:

{
	"domain" : "example.com",
	"service" : "67f65329-0dc3-4499-8522-86afc64df17d",
	"source" : "remote",
	"master" : "192.0.2.25"
}

Specifying no source results in the domain being created with a local master.

The response to this request is the complete service object, as above.

Node: /service/domain/delete

Request:

{
	"domain" : "example.com",
	"service" : "67f65329-0dc3-4499-8522-86afc64df17d"
}

The response to this request is empty.