Skip to content

Latest commit

 

History

History
432 lines (339 loc) · 10 KB

API.md

File metadata and controls

432 lines (339 loc) · 10 KB
Raw

Overview

This document describes important RESTful APIs of STF. These APIs may open the door to new creative uses of STF. You can use these APIs for running UI tests on real devices. Integrating STF with CI tools such as Jenkins etc. Building device farm for data extraction for smartphone app data mining. You can even use these apis for creating bitcoin mining farm. Possibilities are infinite!

PS: Please, don't forget to give us our share, if you successfully mine some bitcoins ;).

Let's talk about APIs now. Internally STF uses Swagger interface for its API implementation. For those who don't know about Swagger, Swagger provides specifications for RESTful apis. By using it you can generate documentations and client SDKs in various language automatically for Swagger-enabled apps. This gives you power to use STF APIs in any language of your favorite. You can read more about Swagger at here.

Swagger Documentations

You can check swagger documentations for STF APIs from here. From this document you can check latest APIs, their definitions, usage etc.

APIs

Sample Usages

Authentication

STF uses oauth2 for RESTful APIs authentication. In order to use APIs, you will first need to generate an access token. Access tokens can be easily generated from STF UI. Just go to the Settings tab and generate new access token from keys section. Don't forget to save this token somewhere, you will not be able to see it again.

Put access token in the header of every request

Curl Sample

curl -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/user

NodeJS Sample

var Swagger = require('swagger-client');

var SWAGGER_URL = 'https://stf.example.org/api/v1/swagger.json';
var AUTH_TOKEN  = 'xx-xxxx-xx';

// Without Promise
var client = new Swagger({
  url: SWAGGER_URL
, authorizations: {
    accessTokenAuth: new Swagger.ApiKeyAuthorization('Authorization', 'Bearer ' + AUTH_TOKEN, 'header')
  }
, success: function() {
    client.user.getUser(function(user) {
      console.log(user.obj)
    })
 }
});

// Using Promise
var clientWithPromise = new Swagger({
  url: SWAGGER_URL
, usePromise: true
, authorizations: {
    accessTokenAuth: new Swagger.ApiKeyAuthorization('Authorization', 'Bearer ' + AUTH_TOKEN, 'header')
  }
})

clientWithPromise.then(function(api) {
  api.user.getUser()
    .then(function(res) {
      console.log(res.obj.user.email)
      // [email protected]
    })
})

Devices

/devices

List all STF devices including disconnected or offline ones

GET /api/v1/devices

Curl Sample

curl -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/devices

NodeJS Sample

clientWithPromise.then(function(api) {
  api.devices.getDevices()
    .then(function(res) {
      console.log(res.obj.devices.length)
      // 50
    })
})

// OR
clientWithPromise.then(function(api) {
  api.devices.getDevices({fields: 'serial,using,ready'})
    .then(function(res) {
      console.log(res.obj.devices)
      // [ { serial: 'xxxx', using: false, ready: true },
      //   { serial: 'yyyy', using: false, ready: true }]
    })
})

/devices/{serial}

Provide information to specific device

GET /api/v1/devices/{serial}

Curl Sample

curl -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/devices/xxxxxxxxx

NodeJS Sample

clientWithPromise.then(function(api) {
  api.devices.getDeviceBySerial({serial: 'xxxx'})
    .then(function(res) {
      console.log(res.obj.device.serial)
      // xxxx
    })
})

// OR
clientWithPromise.then(function(api) {
  api.devices.getDeviceBySerial({serial: 'xxxx', fields: 'serial,using,ready'})
    .then(function(res) {
      console.log(res.obj.device)
      // { serial: 'xxxx', using: false, ready: true }
    })
})

User

/user

Provides current authenticated user information

GET /api/v1/user

Curl Sample

curl -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/user

NodeJS Sample

clientWithPromise.then(function(api) {
  api.user.getUser()
    .then(function(res) {
      console.log(res.obj.user.email)
      // [email protected]
    })
})

/user/devices

Provide devices owned by user

GET /api/v1/user/devices

Curl Sample

curl -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/user/devices

NodeJS Sample

clientWithPromise.then(function(api) {
  api.user.getUserDevices()
    .then(function(res) {
      console.log(res.obj.devices.length)
      // 1
    })
})

// OR
clientWithPromise.then(function(api) {
  api.user.getUserDevices({fields: 'serial,using,ready'})
    .then(function(res) {
      console.log(res.obj.devices)
      // [ { serial: 'xxxx', using: true, ready: true } ]
    })
})

Add new device for user

POST /api/v1/user/devices

Curl Sample

curl -X POST --header "Content-Type:application/json" --data '{"serial":"EP7351U3WQ"}' -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/user/devices

NodeJS Sample

var device = {serial: 'yyyy', timeout: 900000 }

clientWithPromise.then(function(api) {
  return api.user.addUserDevice({device: device})
    .then(function(res) {
      console.log(res.obj)
      // { success: true, description: 'Device successfully added' }
    })
})
.catch(function(err) {
  console.log(err)
})

Delete a device from user

DELETE /api/v1/user/devices/{serial}

Curl Sample

curl -X DELETE -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/user/devices/{serial}

NodeJS Sample

clientWithPromise.then(function(api) {
  return api.user.deleteUserDeviceBySerial({serial: 'yyyy'})
    .then(function(res) {
      console.log(res.obj)
      // { success: true, description: 'Device successfully removed' }
    })
})
.catch(function(err) {
  console.log(err)
})

/user/devices/{serial}/remoteConnect

Remote Connect

POST /api/v1/user/devices/{serial}/remoteConnect

Curl Sample

curl -X POST --header "Content-Type:application/json" -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/user/devices/{serial}/remoteConnect

NodeJS Sample

clientWithPromise.then(function(api) {
  return api.user.remoteConnectUserDeviceBySerial({serial: 'CB5125LBYM'})
    .then(function(res) {
      console.log(res.obj.remoteConnectUrl)
      // $PROVIDER_IP:16829
    })
})
.catch(function(err) {
  console.log(err)
  // {"success":false,
  //  "description":"Device is not owned by you or is not available"}' }
})

Remote Disconnect

DELETE /api/v1/user/devices/{serial}/remoteConnect

Curl Sample

curl -X DELETE -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/user/devices/{serial}/remoteConnect

NodeJS Sample

clientWithPromise.then(function(api) {
  return api.user.remoteDisconnectUserDeviceBySerial({serial: 'CB5125LBYM'})
    .then(function(res) {
      console.log(res.obj)
      // { success: true,
    //     description: 'Device remote disconnected successfully' }
    })
})
.catch(function(err) {
  console.log(err)
  // {"success":false,"description":"Device is not owned by you or is not available"}
})

Sample Usages

Connect Device

// stf-connect.js

var Swagger = require('swagger-client');

var SWAGGER_URL = 'https://stf.example.org/api/v1/swagger.json';
var AUTH_TOKEN  = 'xx-xxxx-xx';

// Using Promise
var clientWithPromise = new Swagger({
  url: SWAGGER_URL
, usePromise: true
, authorizations: {
    accessTokenAuth: new Swagger.ApiKeyAuthorization('Authorization', 'bearer ' + AUTH_TOKEN, 'header')
  }
})

var serial = process.argv.slice(2)[0]

clientWithPromise.then(function(api) {
  return api.devices.getDeviceBySerial({
    serial: serial
  , fields: 'serial,present,ready,using,owner'
  }).then(function(res) {
      // check if device can be added or not
      var device = res.obj.device
      if (!device.present || !device.ready || device.using || device.owner) {
        throw new Error('Device is not available')
      }

      return api.user.addUserDevice({
        device: {
          serial: device.serial
        , timeout: 900000
        }
      }).then(function(res) {
        if (!res.obj.success) {
          throw new Error('Could not connect to device')
        }

        return api.user.remoteConnectUserDeviceBySerial({
          serial: device.serial
        }).then(function(res) {
          console.log(res.obj.remoteConnectUrl)
        })
      })
  })
})
node stf-connect.js xxxx
# $PROVIDR_IP:16829

Disconnect Device

var Swagger = require('swagger-client');

var SWAGGER_URL = 'https://stf.example.org/api/v1/swagger.json';
var AUTH_TOKEN  = 'xx-xxxx-xx';

// Using Promise
var clientWithPromise = new Swagger({
  url: SWAGGER_URL
, usePromise: true
, authorizations: {
    accessTokenAuth: new Swagger.ApiKeyAuthorization('Authorization', 'bearer ' + AUTH_TOKEN, 'header')
  }
})

var serial = process.argv.slice(2)[0]

clientWithPromise.then(function(api) {
  return api.user.getUserDevices({
    serial: serial
  , fields: 'serial,present,ready,using,owner'
  }).then(function(res) {
      // check if device can be added or not
      var devices = res.obj.devices

      var hasDevice = false
      devices.forEach(function(device) {
        if(device.serial === serial) {
          hasDevice = true;
        }
      })

      if (!hasDevice) {
        throw new Error('You are not owner')
      }

      return api.user.deleteUserDeviceBySerial({
        serial: serial
      }).then(function(res) {
        if (!res.obj.success) {
          throw new Error('Could not disconnect to device')
        }

        console.log('Device disconnected successfully!')
      })
  })
})
node stf-disconnect.js xxxx
# Device disconnected successfully!