Matching results

Gateway

A gateway is a hardware that can be managed by AirVantage. Currently, several kind of gateways are supported.
It can be :

  • an AirLink device: GX400, GX440, LS300, Raven XE, Raven XT, Raven X, PinPoint X, PinPoint XT, MP, FXT009, GL6100.
  • an AirPrime module: WMP100, WMP150, etc.
  • or a generic Linux gateway.

Read only fields are computed by AirVantage and can only be seen on response fragments sent by find, create, or edit requests.

Field Description Read Only Type
uid Gateway's unique identifier. true uid
imei International Mobile Equipment Identity of the gateway. false string
macAddress MAC address of the gateway. false string
serialNumber Serial number of the gateway. false string
type Type of the gateway false string
state Shows the state of the gateway. Possible values can be INVENTORY, BEING_TRANSFERRED. true enum
creationDate Shows the creation date of the gateway true timestamp
labels Gateways can be labeled with a list of labels. false string array
metadata key/value pairs false map

This is a complete representation of a Gateway. This fragment can be used for create or edit requests. Please refer to the fields section to know which fields can be modified.

{
    "uid": "",
    "imei": "",
    "macAddress": "",
    "serialNumber": "",
    "type": "",
    "metadata": [ 
       {
          "key" : "",
          "value" : ""
       }],
    "labels": ["Label1", "Label2"],
    "creationDate": ,
    "state": ""
}

/api/v1/gateways

Returns a paginated list of gateways with their complete details.

It is possible to restrain the result list using criteria parameters.

The fields parameter has to be defined in order to specify the attributes of the gateway which will be returned.
If fields parameter is missing, only the following attributes of the gateway are returned: uid, state, imei, macAddress, serialNumber, type, creationDate.

More information about paging, filtering, and sorting here

Request

GET https://na.airvantage.net/api/v1/gateways?fields=uid,imei,serialNumber&state=INVENTORY

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
{
   "items":    [
            {
         "uid": "082ff307d428461a9eb24f3c8b68f756",
         "imei": "353270041012745",
         "serialNumber": null
      },
            {
         "uid": "96393342be2649fea1cb144ce13d0b5d",
         "imei": "353270041012749",
         "serialNumber": null
      }
   ],
   "count": 2,
   "size": 2,
   "offset": 0
}
Name Description Use Default Type Operand
uid Finds a gateway whose uid match with the specified id. optional null uid =
imei Finds gateways by their International Mobile Equipment Identity optional null string like
macAddress The gateway's mac address. Notice that mac addresses are saved with colon( : ) separators. optional null string like
serialNumber Finds gateways by serial number . optional null string like
labels Returns all gateways labeled as the specified string. Several labels can be set. optional null string array in
type Finds gateways by their type. optional null string like
states Returns all gateways whose state is in the given list. States are INVENTORY, BEING_TRANSFERRED. optional null string array in
metadata Finds gateways matching the given metadata. optional null string map with the following format: key1:value1,key2:value2,... = for the key and like for the value
assigned Returns all gateways assigned (or not) to a system. optional null boolean =
company Set the context company. optional caller's company uid =
HTTP Method GET
Requires Authentication Yes
Rate Limited Yes
Headers None
Permissions entities.gateways.view
Order by creationDate
Fields uid, state, imei, macAddress, serialNumber, type, creationDate, metadata, labels

/api/v1/gateways/{uid}

Returns detailed information about the specified gateway.

Request

GET https://na.airvantage.net/api/v1/gateways/1cc562f8ec1340e79214f2113db751f6

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
{
   "type": "gatewayType",
   "labels":    [
      "Label1",
      "Label2"
   ],
   "uid": "1cc562f8ec1340e79214f2113db751f6",
   "metadata" : [
      {
         "key" : "env",
         "value" : "gatewayEnv"
      }
   ],
   "macAddress": null,
   "serialNumber": "458555527",
   "imei": null,
   "creationDate": "1337948436603",
   "state": "INVENTORY"
}
Name Description
gateway.unknown Raised when the 'uid' points to an unknown gateway.
HTTP Method GET
Requires Authentication Yes
Rate Limited Yes
Headers None
Permissions entities.gateways.view

/api/v1/gateways

Creates a new gateway. Response returns the gateway with its uid.

At least one of imei, serialNumber or macAddress must be set. These fields have to be unique. Read only fields will be ignored.

Request

POST https://na.airvantage.net/api/v1/gateways
Content-Type: application/json
...
{
   "macAddress": "01:a2:03:78:05:06",
   "serialNumber": "CA0125698737",
   "imei": "187496536874560",
   "type": "gatewayType1",
   "metadata" : [
      {
         "key" : "env",
         "value" : "gatewayEnv1"
      }
    ],
    "labels":    [
      "Label1",
      "Label2"
    ]
}      

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
   "uid": "cde6b26d3c344c0780f06caa26cf7113",
   "labels":    [
      "Label1",
      "Label2"
   ],
   "macAddress": "01:a2:03:78:05:06",
   "serialNumber": "CA0125698737",
   "imei": "187496536874560",
   "type": "gatewayType1",
   "metadata" : [
      {
         "key" : "env",
         "value" : "gatewayEnv1"
      }
    ],
   "creationDate": "1337948436603",
   "state": "INVENTORY"
}
Name Description Use Default Type
company Set the context company. optional caller's company uid
Name Description
gateway.missing.identifiers At least one of 'imei', 'macAddress' or 'serialNumber' has to be set.
gateway.not.unique.identifiers One of 'imei', 'macAddress' or 'serialNumber' is not unique.
gateway.invalid.metadata Blank or duplicate keys are not allowed.
gateway.invalid.mac.address Mac address must be a string with the following format: six groups of two hexadecimal digits,separated by colons (:). E.g. 01:23:45:67:89:ab
company.unknown The given company is unknown.
HTTP Method POST
Requires Authentication Yes
Rate Limited Yes
Headers Content-type: application/json
Permissions entities.gateways.create

/api/v1/gateways/{uid}

Edits the gateway identified by the uid of the request. If the gateway is linked to a system in 'READY', 'DEPLOYED', or 'BEING_TRANSFERED' state, then only the labels can be edited. Otherwise, you can edit all the fields.


NB: It is not necessary to send the whole JSON block to edit fields. Only fields sent to the service will be updated.

Request

PUT https://na.airvantage.net/api/v1/gateways/1cc562f8ec1340e79214f2113db751f6
Content-Type: application/json
...
{
    "imei" : "353270040002745",
    "macAddress" : "0C:12:24:F1:10:A0",
    "serialNumber" : "007",
    "type" : "M2MBoxPro",
    "metadata" : [
       {
          "key" : "env",
          "value" : "OpenAT"
       }
    ],
    "labels" : ["Label1","Label2"]
}

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
   "uid": "1cc562f8ec1340e79214f2113db751f6",
   "type": "M2MBoxPro",
   "labels":    [
      "Label1",
      "Label2"
   ],
   "metadata" : [
      {
         "key" : "env",
         "value" : "OpenAT"
      }
   ],
   "imei": "353270040002745",
   "macAddress": "0C:12:24:F1:10:A0",
   "serialNumber": "007",
   "creationDate" : "1337948436603",
   "state": "INVENTORY"
}
Name Description
gateway.unknown The uid of the gateway is unknown.
gateway.being.transferred The gateway is being transferred, it is not editable.
gateway.missing.identifiers At least one of 'imei', 'macAddress' or 'serialNumber' has to be set.
gateway.not.unique.identifiers One of 'imei', 'macAddress' or 'serialNumber' is not unique.
gateway.invalid.mac.address Mac address must be a string with the following format: six groups of two hexadecimal digits,separated by colons (:). E.g. 01:23:45:67:89:ab
system.invalid.state Only labels can be updated when system state is different from INVENTORY or MAINTENANCE.
system.communication.identifier.already.used The generated communication identifier is not unique, another system already use it.
company.unknown The given company is unkown.
HTTP Method PUT
Requires Authentication Yes
Rate Limited Yes
Headers Content-type: application/json
Permissions entities.gateways.edit

/api/v1/gateways/{uid}

Deletes a specific gateway from the AirVantage. To delete a gateway it does not have to be assigned to any system.

Request

DELETE https://na.airvantage.net/api/v1/gateways/1cc562f8ec1340e79214f2113db751f6

Response
200 OK

HTTP/1.1 200 OK
Content-Length: 0
    
Name Description
gateway.unknown Raised when the 'uid' points to an unknown gateway.
gateway.assigned Raised when the gateway is assigned to a system.
HTTP Method DELETE
Requires Authentication Yes
Rate Limited Yes
Headers -
Permissions entities.gateways.delete

/api/v1/operations/gateways/import

Imports and creates gateways from a CSV file.

Returns the uid of the created operation.

Request

POST https://na.airvantage.net/api/v1/operations/gateways/import
Content-type: multipart/mixed; boundary="BoundaryUgix6QHMxLwJ4siU"
--BoundaryUgix6QHMxLwJ4siU
Content-Disposition: form-data; name="file"; filename="file.csv"
Content-Type: text/csv
// CSV attached
...
--BoundaryUgix6QHMxLwJ4siU
Content-Disposition: form-data; name="parameters"; filename="parameters.json"
Content-Type: application/json
// JSON attached
{
    "notify" : true,
    "callback" : "callback_url"
}
--BoundaryUgix6QHMxLwJ4siU--

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
  "operation":"4b89657f63aac4b299c1d46e98a495326"
}
Name Description Use Default Type
company Set the context company. optional caller's company uid
Header Description Use
IMEI The imei of the new gateway.
Expected format : a string of 15 digits
optional
MAC ADDRESS The mac address of the new gateway.
Expected format : six groups of two hexadecimal digits, separated by colons (:). (E.g. 01:23:45:67:89:AB)
optional
SERIAL NUMBER The serial number of the new gateway. optional
TYPE The gateway type (E.g. M2MBoxPro) optional
METADATA[metadataName] The gateway metadata (E.g. ENV for environnement) optional
LABELS The labels of the new gateway, separated by a '|' character. optional

At least one of the gateway identifiers (Imei, Mac Address, Serial number) is expected.

{
    "notify" : true|false,
    "callback" : "callback_url"
}
                    
Field Description Use Default Type
notify Send an email notification to the user calling this method when the operation finishes. optional false boolean
callback The url that will be called when the operation state changes. The url has the following pattern : http(s)://(user:password@)www.yourhost.com/your_rest_service optional string
Name Description
file.unreadable File is unreadable
file.header.missing CSV header is missing
csv.header.unknown.column CSV header column is unknown
file.missing.data File contains no data
file.too.large Files cannot be more than 10MB
HTTP Method POST
Requires Authentication Yes
Rate Limited Yes
Headers Content-type: application/octet-stream
Permissions entities.gateways.create

/api/v1/operations/gateways/label

Adds or removes labels to gateways matching a given criteria. When no criteria are set, all gateways in the company will be labelled.

Request

POST https://na.airvantage.net/api/v1/operations/gateways/label
Content-Type: application/json
...
{
   "labels" : {
      "add" :  ["france"]
   },
   "criteria" : {
      "type" : "M2MBoxPro",
      "labels" : ["test"]
   }
}
                                

This request adds the label 'france' to all gateways matching the type 'M2MBoxPro' and labeled 'test'.


Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
   "operation":"4b89657f63aac4b299c1d46e98a495326"
}
                                

Returns the id of the labeling operation.


{
   "notify" : ,
   "callback" : ,
   "labels" : {                   
      "add" : ["Label1", ...],
      "remove" : ["Label2", ...]
   },
   "criteria" : {
      "uids" : []
      "labels" : [],
      "serialNumber" : ,
      "imei" : ,
      "macAddress" : ,
      "type" : ,
      "states" : [],
      "assigned" : ,
      "metadata" : {
         "key1" : "value1",
         "key2" : "value2",
         ...
      }
   },
   "dependsOn" : {
      "operation" : "uid",
      "states" : ["FAILURE"]
   },
   "identifiers" : {
      "serialNumber" : ["serial1", "serial2"],
      "imei" : ["imei1", "imei2"],
      "macAddress" : ["mac1", "mac2"]
   }
}
                            

Add or remove labels should be required
Either 'criteria' or 'dependsOn' should be set.

Field Description Use Default Type
notify Send an email notification to the user calling this method when the operation finishes optional false boolean
callback The url that will be called when the operation state changes. The url has the following pattern : http(s)://(user:password@)www.yourhost.com/your_rest_service optional string
labels.add The list of labels to add optional string
labels.remove The list of labels to remove optional string
dependsOn.operation Operation to be used to launch this operation
In other words, the tasks of the new operation will start only when the tasks of specified operation will be finished.
required if 'dependsOn' set uid
dependsOn.states States of the tasks which will be used as input of this operation.
Possible values are : SUCCESS, FAILURE and CANCELLED.
If null or empty, all tasks from the parent operation will be used as input of this operation.
optional SUCCESS,FAILURE,CANCELLED string array
identifiers List of identifiers to be used to identify gateway. The understandable identifiers are : serial number, IMEI and MAC address.
A maximum of 5000 identifiers can be provided.
optional string
identifiers.serialNumber List of serial number to be used to identify gateways.
A maximum of 5000 serial numbers can be provided.
optional string
identifiers.imei List of IMEI to be used to identify gateways.
A maximum of 5000 IMEIs can be provided.
optional string
identifiers.macAddress List of MAC address to be used to identify gateways.
A maximum of 5000 MAC addresses can be provided.
optional string
criteria.uids Labels all gateways whose uid matches with the specified ids. optional string
criteria.labels Labels all gateways which have one of the specified labels. optional string
serialNumber Labels all gateways whose serial number contains the given string. optional string
imei Labels all gateways whose imei contains the given string. optional string
macAddress Labels all gateways whose mac address contains the given string. optional string
type Labels all gateways whose type contains the given string. optional string
states Labels all gateways matching the specified states. States are : INVENTORY, BEING_TRANSFERRED. optional string
assigned Labels all gateways assigned (or not) to a system. Expected value : true/false. optional boolean
metadata Labels all gateways matching the specified metadata. optional string
Name Description Use Default Type Operand
company Set the context company. optional caller's company uid =
Name Description
label.missing The list of label to add or remove is empty.
label.amount.exceeded The number of labels to add or remove is greater than 100.
selection.empty There is no gateway matching the given criteria.
selection.invalid The selection is invalid. The possible causes are :
  • Only one of the following attributes has to be set : criteria, dependsOn
  • 'dependsOn' is defined but 'dependsOn.operation' is not set
HTTP Method POST
Requires Authentication Yes
Rate Limited Yes
Headers Content-type: application/json
Permissions entities.gateways.edit

/api/v1/operations/gateways/delete

Deletes several gateways. As this operation may be long, depending on the number of gateways to delete, it is done asynchronously. Gateways linked to a system will not be deleted and the task associated to these gateways will fail.

Request

POST https://na.airvantage.net/api/v1/operations/gateways/delete
Content-Type: application/json
...
{
   "gateways" : {
      "uids" : ["16199496f6d24f0691fa006ef53e5592"]
   }
}

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
   "operation":"4b89657f63aac4b299c1d46e98a495326"
}
Name Description Use Default Type
company Set the context company. optional caller's company uid
{
   "notify" : true|false,
   "callback" : "callback URL",
   "gateways" : {
      "label" : "label",
      "uids" : ["uid1", ...],
      "dependsOn" : {
         "operation" : "uid",
         "states" : ["FAILURE"]
      }
   }
}
Field Description Use Default Type
notify Send an email notification to the user calling this method when the operation finishes optional false boolean
callback The url that will be called when the operation state changes. The url has the following pattern : http(s)://(user:password@)www.yourhost.com/your_rest_service optional string
gateways.label Label name. All gateways linked to the label will be incorporated to the operation required string
gateways.uids List of gateway uids to be used to launch the operation required uid
gateways.dependsOn.operation Identifier of the operation to be used to launch this operation
In other words, the tasks of the new operation will start only when the tasks of specified operation will be finished.
required if 'dependsOn' set uid
gateways.dependsOn.states States of the tasks which will be used as input of this operation.
Possible values are : SUCCESS, FAILURE and CANCELLED.
If null or empty, all tasks from the parent operation will be used as input of this operation.
optional SUCCESS,FAILURE,CANCELLED string array
Name Description
selection.empty The list of gateway uids is empty or no gateway found for the specified label.
selection.invalid The selection is invalid. Only one of the following attributes has to be set : label, uids, dependsOn.
selection.max.uid.reached The list of gateway uids contains more than 100 uids.
label.unknown The specified label is unknown
operation.unknown The specified 'dependsOn' operation is unknown
gateway.assigned Shown in the operation report. Raised when the gateway cannot be deleted because it is still assigned to a system.
gateway.unknown Shown in the operation report. Raised when the gateway cannot be found in AirVantage.
HTTP Method POST
Requires Authentication Yes
Rate Limited Yes
Headers Content-type: application/json
Permissions entities.gateways.delete

/api/v1/operations/gateways/transfer

Transfers gateways to a partner company.

The group of gateways to transfer can be specified using a label or a set of 100 uids. After launching the transfer, a request will be sent to the destination. The operation will not be finished until the request has been treated by the destination company.

Returns the uid of the created operation.

Request

POST https://na.airvantage.net/api/v1/operations/gateways/transfer
Content-Type: application/json
...
{
  "message" : "Accept this!!",
  "destination" : "787ef34132fe89734acb9871",
  "gateways" : {
     "uids" : ["gate1", "gate2"]
  }
}

This request sends a transfer request to the destination company. The destination company has to be partner of the source company.


Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
   "operation":"4b89657f63aac4b299c1d46e98a495326"
}

Send a transfert request

               
{
    "notify" : true,
    "callback" : "callback URL",
    "message" : "xxx",           
    "destination" : "xxx",        
    "gateways" : {               
       "uids" : ["xxx", "yyy"],  
       "label" : "zzz"
    }
}
                            
Field Description Use Default Type
notify Send an email notification to the user calling this method when the operation finishes optional false boolean
callback The url that will be called when the operation state changes. The url has the following pattern : http(s)://(user:password@)www.yourhost.com/your_rest_service optional string
gateways.label Gateway selection by label optional string list
gateways.uids Gateway selection by list of uids optional uids list
message Message to explain the purpose of the transfer optional string
destination The uid of the destination company required uid

Use either 'gateways.label' or 'gateways.uids' but not both.


Accept a transfert request

The following API has to be used to accept a gateways transfer: Accept. When you accept a set of gateways, you can specify a label which will be applied to all the transfered gateways. The label is optional and created if it does not exist.

               
{
   "message" : "", 
   "data" : {
      "label" : ""          
   }                       
}
                            
Field Description Use Default Type
message An acceptance message to be returned to the request sender. optional string
data.label The label to add to the transfered gateways. optional string
Name Description Use Default Type
company Set the context company. optional caller's company uid
Name Description
company.missing The destination company identifier is missing.
partner.unknown The destination company is not a partner.
gateway.unknown One of the specifed uid doesn't correspond to an existing gateway.
selection.empty The given label selection returns no gateway.
selection.invalid The given selection is either empty or defined both uids and label.
selection.max.uid.reached The given selection contains more than 100 uids.
HTTP Method POST
Requires Authentication Yes
Rate Limited Yes
Headers Content-type: application/json
Permissions entities.gateways.transfers.create
TOP