mirror of
https://github.com/openstf/stf
synced 2025-10-04 10:19:30 +02:00
436 lines
10 KiB
Markdown
436 lines
10 KiB
Markdown
## 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](http://swagger.io/) 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](http://swagger.io/getting-started/).
|
|
|
|
### Swagger Documentations
|
|
|
|
You can check swagger documentations for STF APIs from [here](https://vbanthia.github.io/angular-swagger-ui). From this document you can check latest APIs, their definitions, usage etc.
|
|
|
|
## APIs
|
|
- [Authentication](#authentication)
|
|
- [Devices](#devices)
|
|
- [User](#user)
|
|
|
|
## Sample Usages
|
|
- [ConnectDevice](#connect-device)
|
|
- [DisconnectDevice](#disconnect-device)
|
|
|
|
### 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
|
|
```bash
|
|
curl -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/user
|
|
```
|
|
|
|
NodeJS Sample
|
|
```js
|
|
|
|
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)
|
|
// vishal@example.com
|
|
})
|
|
})
|
|
```
|
|
|
|
### Devices
|
|
#### /devices
|
|
|
|
**List all STF devices including disconnected or offline ones**
|
|
|
|
```bash
|
|
GET /api/v1/devices
|
|
```
|
|
|
|
Curl Sample
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/devices
|
|
```
|
|
|
|
NodeJS Sample
|
|
|
|
```js
|
|
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**
|
|
|
|
```bash
|
|
GET /api/v1/devices/{serial}
|
|
```
|
|
|
|
Curl Sample
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/devices/xxxxxxxxx
|
|
```
|
|
|
|
NodeJS Sample
|
|
|
|
```js
|
|
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**
|
|
|
|
```bash
|
|
GET /api/v1/user
|
|
```
|
|
|
|
Curl Sample
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/user
|
|
```
|
|
|
|
NodeJS Sample
|
|
|
|
```js
|
|
clientWithPromise.then(function(api) {
|
|
api.user.getUser()
|
|
.then(function(res) {
|
|
console.log(res.obj.user.email)
|
|
// vishal@example.com
|
|
})
|
|
})
|
|
```
|
|
|
|
#### /user/devices
|
|
|
|
**Provide devices owned by user**
|
|
|
|
```bash
|
|
GET /api/v1/user/devices
|
|
```
|
|
|
|
Curl Sample
|
|
|
|
```bash
|
|
curl -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/user/devices
|
|
```
|
|
|
|
NodeJS Sample
|
|
|
|
```js
|
|
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**
|
|
|
|
```bash
|
|
POST /api/v1/user/devices
|
|
```
|
|
|
|
Curl Sample
|
|
|
|
```bash
|
|
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
|
|
|
|
```js
|
|
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**
|
|
|
|
```bash
|
|
DELETE /api/v1/user/devices/{serial}
|
|
```
|
|
|
|
Curl Sample
|
|
|
|
```bash
|
|
curl -X DELETE -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/user/devices/{serial}
|
|
```
|
|
|
|
NodeJS Sample
|
|
|
|
```js
|
|
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**
|
|
|
|
```bash
|
|
POST /api/v1/user/devices/{serial}/remoteConnect
|
|
```
|
|
|
|
Curl Sample
|
|
|
|
```bash
|
|
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
|
|
|
|
```js
|
|
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**
|
|
|
|
```bash
|
|
DELETE /api/v1/user/devices/{serial}/remoteConnect
|
|
```
|
|
|
|
Curl Sample
|
|
|
|
```bash
|
|
curl -X DELETE -H "Authorization: Bearer OAUTH-TOKEN" https://stf.example.org/api/v1/user/devices/{serial}/remoteConnect
|
|
```
|
|
|
|
NodeJS Sample
|
|
|
|
```js
|
|
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
|
|
|
|
```js
|
|
// 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 client = new Swagger({
|
|
url: SWAGGER_URL
|
|
, usePromise: true
|
|
, authorizations: {
|
|
accessTokenAuth: new Swagger.ApiKeyAuthorization('Authorization', 'Bearer ' + AUTH_TOKEN, 'header')
|
|
}
|
|
})
|
|
|
|
var serial = process.argv.slice(2)[0]
|
|
|
|
client.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) {
|
|
console.log('Device is not available')
|
|
return
|
|
}
|
|
|
|
// add device to user
|
|
return api.user.addUserDevice({
|
|
device: {
|
|
serial: device.serial
|
|
, timeout: 900000
|
|
}
|
|
}).then(function(res) {
|
|
if (!res.obj.success) {
|
|
console.log('Could not add device')
|
|
return
|
|
}
|
|
|
|
// get remote connect url
|
|
return api.user.remoteConnectUserDeviceBySerial({
|
|
serial: device.serial
|
|
}).then(function(res) {
|
|
console.log(res.obj.remoteConnectUrl)
|
|
})
|
|
})
|
|
})
|
|
})
|
|
```
|
|
```bash
|
|
node stf-connect.js xxxx
|
|
# $PROVIDR_IP:16829
|
|
```
|
|
|
|
### Disconnect Device
|
|
|
|
```js
|
|
var Swagger = require('swagger-client');
|
|
|
|
var SWAGGER_URL = 'https://stf.example.org/api/v1/swagger.json';
|
|
var AUTH_TOKEN = 'xx-xxxx-xx';
|
|
|
|
var client = new Swagger({
|
|
url: SWAGGER_URL
|
|
, usePromise: true
|
|
, authorizations: {
|
|
accessTokenAuth: new Swagger.ApiKeyAuthorization('Authorization', 'Bearer ' + AUTH_TOKEN, 'header')
|
|
}
|
|
})
|
|
|
|
var serial = process.argv.slice(2)[0]
|
|
|
|
client.then(function(api) {
|
|
return api.user.getUserDevices({
|
|
serial: serial
|
|
, fields: 'serial,present,ready,using,owner'
|
|
}).then(function(res) {
|
|
// check if user has that device or not
|
|
var devices = res.obj.devices
|
|
var hasDevice = false
|
|
|
|
devices.forEach(function(device) {
|
|
if(device.serial === serial) {
|
|
hasDevice = true;
|
|
}
|
|
})
|
|
|
|
if (!hasDevice) {
|
|
console.log('You do not own that device')
|
|
return
|
|
}
|
|
|
|
return api.user.deleteUserDeviceBySerial({
|
|
serial: serial
|
|
}).then(function(res) {
|
|
if (!res.obj.success) {
|
|
console.log('Could not disconnect')
|
|
return
|
|
}
|
|
console.log('Device disconnected successfully!')
|
|
})
|
|
})
|
|
})
|
|
```
|
|
|
|
```bash
|
|
node stf-disconnect.js xxxx
|
|
# Device disconnected successfully!
|
|
```
|