API Integration

Network simulator provides REST API to launch the templates and monitor the real time results of simulation

Introduction

APIs enable IOTIFY network simulator to be integrated into your automated tests. In order to use API from IOTIFY network simulator, you will first need to create a template via our web UI and get an authentication token. Once the template has been created and successfully tested, you could launch and monitor it via our REST APIs.

Global Rate limit

The API are currently rate limited to 1 request every 10 second per client IP. If you exceed the limit, you will receive a HTTP Error 503. If you want to change this limit, please get in touch.

Acquiring an Auth Token

In order to use API, you will first need to acquire a token. Go to your settings page in IoTIFY and click on the API section on the left hand menu. There you could allocate a new token as follows:

The token must be sent as X-Auth header field inside your REST API request. If you are using curl, you could do as follows

curl -X POST -H "X-Auth:"myawesometokenvaluehere" ...

Simulating a Template

Send following information to the rest endpoint of IoTIFY

Parameter

Description

REST Endpoint

https://api.iotify.io/api/v1/template

HTTP Method

POST

Following must be the header contents

HTTP Header

Description

Content-Type

application/json

X-Auth

yourtoken

Payload content

The HTTP POST body must contain following JSON

Parameter

Mandatory

Type

Description

template

YES

string

Exact name of the template in your IoTIFY application. This parameter is case sensitive

repeat

YES

Number

Number of times to repeat the message

interval

YES

Number

The interval between each iteration in seconds.

clients

YES

Number

Number of clients to simulate

parallel

No

Number

The maximum number of clients your server can handle in parallel. Keep it as same as clients field.

delay

No

Number

Delay the actual run of the template by the specified number of the milliseconds.

curl -X POST -H "Content-Type: application/json" -H "X-Auth:1e46d9878285b3f3ef8315802f7a0ad81549" \
-d '{"template": "dweet", "repeat": 5, "interval":10, "clients":1, "delay":0 }' \
https://api.iotify.io/api/v1/template

Response

HTTP Code

Description

400

Launch of the template failed. The response will contain JSON specifying the error reason

200

{success: true, job: “name of the simulation” }

Sample success response

{
"success": true,
"job": "dweet1231-demo-iotify"
}

Sample invalid response

{
"success": false,
"reason": "Invalid Token"
}

If the launch is successful, the REST API will return the job name which is scheduled to be run on the backend. The status of this job can be queried using following API

Getting Simulation status

Send following information to the rest endpoint of IoTIFY to fetch information about the Job

Parameter

Description

REST Endpoint

https://api.iotify.io/api/v1/job

HTTP Method

POST

Following must be the header contents

HTTP Header

Description

Content-Type

application/json

X-Auth

yourtoken

Payload content

The HTTP POST body must contain following JSON

Parameter

Mandatory

Type

Description

job

YES

string

Exact name of the job as received in the response of starting a template.

curl -X POST -H "Content-Type: application/json" -H "X-Auth:1e46d9878285b3f3ef8315802f7a0ad81549" \
-d '{"job": "dweet1231-demo-iotify"}' https://api.iotify.io/api/v1/job

Response

HTTP Code

Description

400

Getting status failed. The response will contain JSON specifying the error reason

200

See below

Sample success response

{
"success": true,
"status": {
"success": 48,
"failure": 0,
"abandoned": 0,
"status": "running",
"start": "2017-11-22T15:02:19.000Z",
"end": "2017-11-22T17:49:09.000Z"
}
}

Sample invalid response

{
"success": false,
"reason": "job can not be found"
}

If the launch is successful, the REST API will return the job status specifying the current status of the job.

If you have additional request for APIs, we would be happy to be in touch.