Searching...

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 endpoint URL to call when the operation state changes. The callback is done using HTTP 'POST' method. 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 endpoint URL to call when the operation state changes. The callback is done using HTTP 'POST' method. 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"]
          },
          "criteria" : {
             "uids" : []
             "labels" : [],
             "serialNumber" : ,
             "imei" : ,
             "macAddress" : ,
             "type" : ,
             "states" : [],
             "assigned" : ,
             "metadata" : {
                "key1" : "value1",
                "key2" : "value2",
                ...
             }
          }
       }
    }
    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 endpoint URL to call when the operation state changes. The callback is done using HTTP 'POST' method. 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
    gateways.criteria.uids Selects all gateways whose uid matches with the specified ids. optional string
    gateways.criteria.labels Selects all gateways which have one of the specified labels. optional string
    gateways.criteria.serialNumber Selects all gateways whose serial number contains the given string. optional string
    gateways.criteria.imei Selects all gateways whose imei contains the given string. optional string
    gateways.criteria.macAddress Selects all gateways whose mac address contains the given string. optional string
    gateways.criteria.type Selects all gateways whose type contains the given string. optional string
    gateways.criteria.states Selects all gateways matching the specified states. States are : INVENTORY, BEING_TRANSFERRED. optional string
    gateways.criteria.assigned Selects all gateways assigned (or not) to a system. Expected value : true/false. optional boolean
    gateways.criteria.metadata Selects all gateways matching the specified metadata. optional string
    Name Description
    selection.empty The list of gateway uids is empty or no gateway found for the specified label or criteria.
    selection.invalid The selection is invalid. Only one of the following attributes has to be set : label, uids, dependsOn, or criteria.
    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 task. Raised when the gateway cannot be deleted because it is still assigned to a system.
    gateway.unknown Shown in the operation task. 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, a set of 100 uids, or criteria. 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.

    This API is deprecated, please use system transfer instead.

    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",
           "criteria" : {
              "uids" : []
              "labels" : [],
              "serialNumber" : ,
              "imei" : ,
              "macAddress" : ,
              "type" : ,
              "states" : [],
              "assigned" : ,
              "metadata" : {
                 "key1" : "value1",
                 "key2" : "value2",
                 ...
              }
           }
        }
    }
                                
    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 endpoint URL to call when the operation state changes. The callback is done using HTTP 'POST' method. optional string
    gateways.label Gateway selection by label optional string list
    gateways.uids Gateway selection by list of uids optional uids list
    gateways.criteria.uids Selects all gateways whose uid matches with the specified ids. optional string
    gateways.criteria.labels Selects all gateways which have one of the specified labels. optional string
    gateways.criteria.serialNumber Selects all gateways whose serial number contains the given string. optional string
    gateways.criteria.imei Selects all gateways whose imei contains the given string. optional string
    gateways.criteria.macAddress Selects all gateways whose mac address contains the given string. optional string
    gateways.criteria.type Selects all gateways whose type contains the given string. optional string
    gateways.criteria.states Selects all gateways matching the specified states. States are : INVENTORY, BEING_TRANSFERRED. optional string
    gateways.criteria.assigned Selects all gateways assigned (or not) to a system. Expected value : true/false. optional boolean
    gateways.criteria.metadata Selects all gateways matching the specified metadata. optional string
    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 or criteria 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