NAV
php

Introduksjon

Velkommen til TerraHosts Control API. Du kan benytte dette APIet til å aksessere og styre dine tjenester hos oss.

Du kan utføre reinstallasjoner av servere, omstart av servere, bestille nye tjenester og mye mer. Dette gjør det enkelt for deg å integrere vårt API i dine egne sider.

Vi vil kontinuerlig tilføre nye kommandoer og muligheter til vårt API.

Autentisering

Control benytter API-keys for å gi tilgang til APIet. Du kan få din helt egen API-key ved å logge inn på våre nettsider https://control.terrahost.no/. Merk deg at denne nøkkelen er personlig, og forbinder deg med din kundekonto hos oss. Alle som har tilgang til din API-key har også tilgang til all din registrerte informasjon hos oss.

For å autentisere deg legger du på api_key-strengen på dine requests mot APIet. Et eksempel er som følger:

?api_key=1238173912093874598674358

Server

Liste over alle servere

Simpel kommando med Curl:

<?php
$ch = curl_init();  

curl_setopt($ch,CURLOPT_URL, "https://control.terrahost.no/api/v1/server/list?api_key=123456789");
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch,CURLOPT_HEADER, false);

$output = curl_exec($ch);
?>

Et eksempel på et svar:

[{
    "success":true,
    "servers":[
    {
        "srv_id":"212",
        "srv_type":"dedicated",
        "srv_vmware_id":"0",
        "srv_vps_type":"",
        "node_id":"0",
        "os_id":"471",
        "os_name":"Debian 7 64-bit",
        "nic_id":"0",
        "srv_status":"1",
        "srv_status_method":"icmp",
        "srv_status_reboot":"0",
        "srv_label":"server.terrahost.no",
        "srv_manufacturer":"Supermicro",
        "srv_model":"X10SLL-F",
        "srv_motherboard":"X10SLL-F",
        "srv_date_created":"02.12.2014",
        "srv_hostname":"server.terrahost.no",
        "srv_bw":"3000",
        "bw_total":1501,
        "bw_used_percent":50,
        "srv_feature_reinstall":"1",
        "srv_feature_mgmt":"1",
        "srv_cores":"",
        "srv_cpus":[
            {
            "cpu_manufacturer":"Intel",
            "cpu_name":"Xeon E5504",
            "cpu_speed":"2.13GHz",
            "cpu_full_name":"Intel Xeon E5504 2.13GHz"
            }
        ],
        "srv_hdds":[
            {
            "datastore_id":"0",
            "hdd_manufacturer":"Samsung",
            "hdd_model":"EVO",
            "hdd_type":"SSD",
            "hdd_size":"120",
            "hdd_space_used":"0"
            }
        ],
        "srv_ip_primary":"84.234.221.1",
        "srv_ips":[
            {
            "ip_id":"999",
            "ip_v4v6":"ipv4",
            "ip_type":"primary",
            "ip_address":"84.234.221.1",
            "ip_netmask":"255.255.255.0",
            "ip_broadcast":"84.234.221.255",
            "ip_gateway":"84.234.221.1",
            "ip_cidr":"84.234.221.0/24",
            "ip_reverse":"static.84.234.221.1.customers.terrahost.no"
            }
        ],
        "srv_ram":"8",
        "srv_ram_type":"DDR3 1333MHz",
        "srv_ram_sticks":"2",
        "srv_location":"DC1"
    }]
}]

Dette endpointet henter alle dine servere fra vårt API i JSON-format. Variablene som returneres kan variere noe utifra hva serveren støtter, utstyr tilgjengelig osv.

Forespørsel

GET https://control.terrahost.no/api/v1/server/list?api_key=<key>

Respons

Atributter Type Beskrivelse
srv_id integer Serverens ID i våre systemer. Benyttes blant annet når man skal utføre en reinstallasjon.
srv_type string Hvilken type server.
srv_vmware_id integer Om dette er en VPS vil denne verdien være VPSens interne ID i vårt cluster.
node_id integer ID til serverens VPS-node.
os_id integer ID til nåværende installerte OS.
os_name string Operativsystemet som for øyeblikket er installert på serveren.
nic_id integer ID til serverens aktive nettverkskort. Dette nettverkskortet benyttes til blant annet reinstallering.
srv_status integer Status på server, sjekkes vært minutt av våre systemer.
srv_status_method string Metode for overvåking av serversystus.
srv_label string Serverns interne label.
srv_manufacturer string Produsent på server om dette er aktuelt.
srv_model string Modellnavn på server om dette er aktuelt.
srv_motherboard string Hovedkort type og modell.
srv_date_created string Dato opprettet i våre systemer.
srv_hostname string Serverens hostnavn.
srv_bw integer Tildelt båndbredde i GB.
bw_total integer Forbrukt båndbredde denne måneden.
bw_used_percent integer Prosentvis fremstilling av forbrukt båndbredde.
srv_feature_reinstall integer Om serveren støtter automatisk reinstallering.
srv_feature_mgmt integer Om serveren støtter strømstyring.
srv_cores integer Antall vCPUs serveren har om dette er en virtuell server.
srv_cpus array Array med prosessorer.
srv_hdds array Array med serverens harddisker.
srv_ip_primary string Serverens primære ip-adresse.
srv_ips array Array med IP-adresser som har tilknytning til serveren.
srv_ram integer RAM i serveren i GB.
srv_ram_type string Type RAM i serveren.
srv_ram_sticks integer Antall RAM-brikker i serveren.
srv_location string Serverens lokasjon.

Omstart av server

Simpel kommando med Curl:

<?php
$ch = curl_init();

curl_setopt($ch,CURLOPT_URL, "https://control.terrahost.no/api/v1/server/123/reboot?api_key=123456789");
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch,CURLOPT_HEADER, false);

$output = curl_exec($ch);
?>

Et eksempel på et svar:

[{
        "success":true,
        "message":"Server rebooted"
}]

Om serveren støtter det, kan du bruke følgende kommando for å ta en omstart av din server.

Forespørsel

GET https://control.terrahost.no/api/v1/server/<id>/reboot?api_key=<key>

Respons

Atributter Type Beskrivelse
success boolean Indikerer om kommandoen ble kjørt uten feil.
message string Tilbakemelding som beskriver utførelsen av handlingen.

Strømstatus på server

Simpel kommando med Curl:

<?php
$ch = curl_init();

curl_setopt($ch,CURLOPT_URL, "https://control.terrahost.no/api/v1/server/<id>/powerstate?api_key=123456789");
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch,CURLOPT_HEADER, false);

$output = curl_exec($ch);
?>

Et eksempel på et svar:

[{
        "success":true,
        "message":"Server is up"
}]

Om serveren er nede

[{
        "success":true,
        "message":"Server is down"
}]

Sjekker strømstatus på din server og gir deg en tilbakemelding i form av “Server is up” eller “Server is down”.

Forespørsel

GET https://control.terrahost.no/api/v1/server/<id>/powerstate?api_key=<key>

Respons

Atributter Type Beskrivelse
success boolean Indikerer om kommandoen ble kjørt uten feil.
message string Tilbakemelding som beskriver utførelsen av handlingen.

Reinstallasjon av server

Simpel kommando med Curl:

<?php
$postData = 'os_internal_id=<id>';
$ch = curl_init();  

curl_setopt($ch,CURLOPT_URL,"https://control.terrahost.no/api/v1/server/<id>/reinstall?api_key=123456789");
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch,CURLOPT_HEADER, false); 
curl_setopt($ch, CURLOPT_POST, count($postData));
curl_setopt($ch, CURLOPT_POSTFIELDS, $postData);    

$output=curl_exec($ch);
?>

Et eksempel på et svar:

[{
        "success":true,
        "message":"Server is being provisioned."
}]

Reinstallasjon for servere som støtter dette. Du sender enkelt en POST-kommando og din server vil reinstalleres. En epost sendes til din kundeepost når installasjonen er fullført

OBS! Root- og administrator-passord tildeles automatisk.

Forespørsel

POST https://control.terrahost.no/api/v1/server/<id>/reinstall?api_key=<key>

Argumenter
os_internal_id påkrevet ID til operativsystemet du ønsker å installere på serveren.
callback_url valgfritt Callback-URL du selv kan sette. Vårt API vil forespørre denne URLen med følgende tillegg: “?srv_id=&reinstall=ok”

Respons

Atributter Type Beskrivelse
success boolean Indikerer om kommandoen ble kjørt uten feil.
message string Tilbakemelding som beskriver utførelsen av handlingen.

Liste over tilgjengelige operativsystemer

Simpel kommando med Curl:

<?php
$ch = curl_init();

curl_setopt($ch,CURLOPT_URL, "https://control.terrahost.no/api/v1/provision/os?api_key=123456789");
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch,CURLOPT_HEADER, false);

$output = curl_exec($ch);
?>

Et eksempel på et svar:

{
    "success":true,
    "os":[
    {
        "id":"74",
        "os_name":"CentOS 6 64-bit"
    },
    {
        "id":"688",
        "os_name":"Ubuntu 14.10 64-bit"
    }]
}

Returnerer en liste med tilgjengelige operativsystem.

Forespørsel

GET https://control.terrahost.no/api/v1/provision/os?api_key=<key>

Respons

Atributter Type Beskrivelse
id integer Intern ID til operativsystemet som benyttes ved reinstallering.
os_name string Navnet på operativsystemet.

Liste over serverpools

Simpel kommando med Curl:

<?php
$ch = curl_init();

curl_setopt($ch,CURLOPT_URL, "https://control.terrahost.no/api/v1/server/pools?api_key=123456789");
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch,CURLOPT_HEADER, false);

$output = curl_exec($ch);
?>

Et eksempel på et svar:

{
    "success":true,
    "pools":[{
        "pool_id":"2",
        "pool_name":"WebPool",
        "pool_servers":[
        {
            "srv_id":"100",
            "srv_hostname":"server.terrahost.no",
            "srv_type":"vps"
        }]
    }]
}

Henter en oversikt over dine serverpools, samt hvillke servere den/de inneholder.

Forespørsel

GET https://control.terrahost.no/api/v1/server/pools?api_key=<key>

Respons

Atributter Type Beskrivelse
success boolean Indikerer om kommandoen ble kjørt uten feil.
pools array Array med pools.
pool_id integer Intern ID til pool.
pool_name string Navnet på serverpoolen.
pool_servers array Array med servere i pool.
srv_id integer Serverens interne ID.
srv_hostname string Serverens hostnavn.
srv_type string Type server, virtuell eller dedikert.

Errors

The Kittn API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The kitten requested is hidden for administrators only
404 Not Found – The specified kitten could not be found
405 Method Not Allowed – You tried to access a kitten with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The kitten requested has been removed from our servers
418 I’m a teapot
429 Too Many Requests – You’re requesting too many kittens! Slown down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.
php