MySAU V2 API released!

I don’t know about you, but I’m excited! A couple of nights ago, we pushed out the MySAU V2 API. If you didn’t know there was a V1 API, that’s ok – neither did I, until I started jotting out the specs for V2 and went to configure the URL’s in our dev/test/prod environments 😉

We’ve wanted to build a nice, solid, and extensible, API for some time – but the old V1 portal just wasn’t the place to start. There are some 230 database tables in V1. Just the basic information on products are stored across five different tables, and that’s before you even go and start hitting lookup tables for statii and relationships. We’d go crazy quite quickly, and so would customers!

 

We’re now 10 months into the V2 Portal redevelopment, and we have enough functionality migrated from V1 to V2, that it has become worthwhile starting to implement an API. And I’ll tell you now, I’m pretty happy with it!

What can you do with the API?

Right now? Quite a bit! You can:

  • manage contacts on your account
  • view and pay invoices
  • list, view, create, and reply to tickets
  • list and view all billed products

And where products have been migrated into V2, you’ll see a ‘refer’ field coming back in the response from the /v2/products endpoint. If you call the referenced endpoint when you go to do your ‘view’, you can pull almost all the information displayed in the portal, as well as get a list of available actions.

What does that mean? Well, it means you can pull the IPMI login details for all of your Dedicated servers, for example. Or you might resell SAU Dedicated servers to your own customers, and want to give them IPMI access right in your own portal. Well, now you can! (We’re going to do a couple of small WHMCS modules for VPS’s, Dedi’s, etc so you can do exactly that very easily 🙂 )

So how do I use the API?

Well, that’s actually incredibly simple. We use the absolutely amazing Swagger for our API Documentation.

Head on over to our API, and have a look. It should be pretty simple to work out what you can do 😉

You can click on any controller to see the individual endpoints available. Before you can do much though, you’re going to need to either add an API Token (This is our suggested primary authentication method), or enable API usage on your account.

API Usage with Username/Password

To enable API Usage using your Username and Password, simply login to MySAU, and navigate to My Details -> Edit Details. In here, you can simply tick the ‘API Enabled’ tickbox, and click save.

When authenticating to the API with username/password, it’s just simple HTTP Basic Auth with username:password

Bear in mind that isn’t the world’s most secure practice. We really suggest you use API Tokens.

API Usage with Tokens

API Tokens are also found in the My Details menu heading, two entries below Edit Details.

Here you’ll see a list of your current API Tokens, their allowed IP’s. When creating or editing a Token, you’ll see a screen like the following.

mysau_api_token_details

You can enable and disable tokens, set allowed IP addresses, and choose from the current set of permissions. We’ll likely refine these at a later stage, as I think ‘manage products’ is perhaps a little broad? I’d be interested to hear customers’ thoughts on that – maybe we should allow a per-product-type granularity?
You can also set allowed IP addresses (Just enter them one per line – we’ll pretty this up next sprint 😉 )

When authenticating against the API with a Token, it is HTTP Basic auth, with token as username, and password field can be blank.

A test call in Swagger-UI

This is the beauty of Swagger. Pop your token into the email/token field, and click Explore. Then lets click on Ticket, and then the GET /v2/ticket item.

mysau_api_testcall_1

Why don’t you click ‘Try it out!’?

mysau_api_testcall_2

Yep, it’s THAT easy. Want to see what’s in one of those tickets? Grab the ID, and scroll down to the GET /v2/ticket/{id} endpoint. Pop the id into the id Parameter field, and click ‘Try it out!’.

mysau_api_testcall_3-1

See why I love Swagger? No need to pop open DHC, curl, or whatever your preferred test case tool happens to be. And even better, Swagger has a codegen module to generate data models and handlers to talk to the API, based on the swagger spec. Although its PHP support is quite outdated and horrendous. I may have to look at rectifying that, when my current free time project is finished!

A quick example

Something a LOT of our customers ask for, is a spreadsheet of the IPMI details for all their services. Well, that’s REALLY easy now. Let me show you a quick example: (Note, 80% of my programming work is in PHP, so that’s what these examples are in 😉 )

<?php  
$i = new IPMIDetails($argv);
$i->run();

class IPMIDetails {  
  private $host;
  private $username;
  private $password = '';
  public function __construct($argv) {
    if (count($argv) < 3) {
      echo "Usage: ipmidetails.php [password]";
      exit(255);
    }
    $this->host = $argv[1];
    $this->username = $argv[2];
    if (isset($argv[3])) {
      $this->password = $argv[3];
    }
  }
  private function callMySAU($function, $method = null, $body = null, $contentType = 'application/json') {
    $url = $this->host . $function;
    $method = strtoupper($method);
    // JSON encode the body if we're not doing a GET or DELETE, and we sent a body array
    if (is_array($body) && !in_array($method, ['GET', 'DELETE'])) {
      $body = json_encode($body);
    }
    if ($method == 'POST') {
      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_POST, true);
      curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    } else if ($method == 'PUT') {
      $ch = curl_init($url);
      curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
      curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
    } else {
      // Build query string
      $ch = curl_init($url . ($body != null ? (strpos($url, '?') > 0 ? '&' : '?') . http_build_query($body) : ''));
      curl_setopt($ch, CURLOPT_CUSTOMREQUEST, ($method ? $method : 'GET'));
    }
    curl_setopt($ch, CURLOPT_USERPWD, $this->username . ':' . ($this->password !== null ? $this->password : ''));
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: ' . $contentType, 'Accept: application/json']);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 30);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    curl_setopt($ch, CURLOPT_MAXREDIRS, 3);
    $response = curl_exec($ch);
    curl_close($ch);
    $jsonData = json_decode($response);
    if (null === $jsonData) {
      return ['status' => 'error'];
    }
    return $jsonData;
  }
  public function run() {
    // Fetch all dedicated server products on our account
    $servers = $this->callMySAU('/v2/dedi-v1');
    foreach($servers as $server) {
      // Fetch each server's details
      $serverdetail = $this->callMySAU($server->refer);
      $fields = ['host' => '', 'username' => '', 'password' => ''];
      foreach($serverdetail->infofields as $field) {
        switch ($field->label) {
        case 'IPMI Url' : {$fields['host'] = $field->value;
          break;
        }
      case 'IPMI Username': {
          $fields['username'] = $field->value;
          break;
        }
      case 'IPMI Password': {
          $fields['password'] = $field->value;
          break;
        }
      }
    }
    echo implode(',', $fields) . "\n";
  }
}

Give it a burl, and off you go!

$ php ipmidetails.php https://api.mysau.com.au 588b57f5535fb805d64d3322ff75d2fe
"http://SAU-ROFLC-OR.ipmi.servercontrol.com.au/","SAU-ROFLC-OR","1772a731"
"http://SAU-OPTER-OR.ipmi.servercontrol.com.au/","SAU-OPTER-DR","98a6f1b9"
"http://SAU-LOLLE-OR.ipmi.servercontrol.com.au/","SAU-LOLLE-OR","1288s7a2"
"http://SAU-RSKAT-OR.ipmi.servercontrol.com.au/","SAU-RSKAT-OR","b9d9a172"

Easy, right?

So, now you see why we’re so excited. We can see we’ll need to refine the API a little once we get some customer feedback, but boy, this is going to ROCK. In a few months we’ll have ordering available via the API. And that’s going to be insane.

Just think, customer hits your website to view your avilable dedicated servers. Your website makes a call to our API to see what we have available for instant provisioning. Customer makes a choice and orders via your billing system. They pass fraud checks, they pay via credit card or paypal. Your billing system makes a provisioning call to our API. 5 mins later, we hit your callback URL with a completion advice, and your billing system pulls all the IP addressing, login, etc info from our API, and emails your customer saying their Dedicated server is online.

Now THAT is sexy. Watch this space.

Leave a Reply

Your email address will not be published. Required fields are marked *