====== API guide ======

===== Push API =====

From WMC v3.0 Software release, the push API changed and more relevant details are provided, such as the cluster ID, device address or gwRecvTime for Message buffering (implemented for release 3.2.7).

In this page, the data is presented as a sample and with a mapping table, to ease the migration between the API versions.

Please, refer to the following screenshots to get information about PushDataUP method:

{{:wiki3:gms_api_pushdataup.png|}}
{{:wiki3:gms_api_pushdataupdto2.png|}}
{{:wiki3:gms_api_enddevicedto_1.png|}}
{{:wiki3:gms_api_enddevicedto_2.png|}}
{{:wiki3:gms_api_gatewayinfodto.png|}}

For the response, here is the information that is available :

{{:wiki3:gms_api_pushdataupdto_response.png|}}
{{:wiki3:gms_api_enddevicedto_response.png|}}

For instance, here is the type of information received by an HTTP push server (network message detail level):

<code>
tda@dsc-tests:~$ nc -klp 8000
POST /dataUp HTTP/1.1
Host: 37.157.227.230:8000
User-Agent: Go-http-client/1.1
Content-Length: 466
Content-Type: application/json
Klk-Unsent-Dataup: true
Accept-Encoding: gzip

{"id":"5d2342ac71a1270001035042","endDevice":{"devEui":"343737394A336F09","devAddr":"24004F6B","cluster":{"id":1}},"fPort":2,"fCntDown":0,"fCntUp":6940,"adr":false,"confirmed":false,"encrypted":false,"payload":"0027800bddfd773b447bf9fede870046","recvTime":1562591916089,"ulFrequency":868.3,"modulation":"LORA","dataRate":"SF12BW125","codingRate":"4/5","gwCnt":1,"gwInfo":[{"gwEui":"7276FF0039030436","rfRegion":"EU868","rssi":-107,"snr":-7,"channel":6,"radioId":1}]}
</code>

==== URL Change ====

The URL is now appended with ''/dataUp'' (instead of ''rxMessage'' in previous versions).

So if the URL provisioned for the cluster is ''https://app.provider.com/xyz/'' then the data will be pushed to ''https://app.provider.com/xyz/dataUp''.

==== Message detail level ====

3 levels are available: ''Payload'', ''Radio'' and ''Network''.

**Payload**: Returns the contents of PushDataUpDto without dataUpNetworkPayload and dataUpRadioPayload. \\
PushDataUpDto example:
<code javascript>
{
  "id": "5c505781bda6af0001221902",
  "endDevice": {
    "devEui": "323831387C346C22",
    "devAddr": "11223344",
    "cluster": {
      "id": 16
    }
  },
  "fPort": 2,
  "fCntDown": 1,
  "fCntUp": 1,
  "adr": false,
  "confirmed": true,
  "encrypted": false,
  "payload": "00266d0985067200000000000000ffff",
  "encodingType": "HEXA",
  "recvTime": 1548769153024,
  "gwRecvTime": 1548769153024,
  "classB": false,
  "delayed": false 
}
</code>

**Radio**: Same as Payload messages + DataUpRadioPayload \\
DataUpRadioPayload example:
<code javascript>
{
...
  "ulFrequency": 867.9,
  "modulation": "LORA",
  "dataRate": "SF12BW125",
  "codingRate": "4/5"
}
</code>

**Network**: same as Radio messages + dataUpNetworkPayload \\
DataUpNetworkPayload example:

<code javascript>
{
...
  "gwCnt": 2,
  "gwInfo": [
    {
      "gwEui": "7276FF002E060234",
      "rfRegion": "EU868",
      "rssi": -89,
      "snr": 10,
      "channel": 4,
      "radioId": 0,
      "antenna": 0
    },
    {
      "gwEui": "7276FF002E060234",
      "rfRegion": "EU868",
      "rssi": -92,
      "snr": 8.2,
      "channel": 20,
      "radioId": 0,
      "antenna": 1
    }
  ]
}
</code>

==== Data sample ====

Here is a sample of a payload with the ''network'' level of detail:

<code javascript>{
  "id": "5c20c07cd7edec0001f847a2",
  "endDevice": {
    "devEui": "343737395C336A08",
    "devAddr": "0132FBCF",
    "cluster": {
      "id": 16
    }
  },
  "fPort": 2,
  "fCntDown": 0,
  "fCntUp": 61,
  "adr": false,
  "confirmed": false,
  "encrypted": false,
  "payload": "0027ff096cfc8218000000000000ffff",
  "encodingType": "HEXA",
  "recvTime": 1545650300180,
  "gwRecvTime": 1545650300180,
  "classB": false,
  "delayed": false,
  "ulFrequency": 868.5,
  "modulation": "LORA",
  "dataRate": "SF12BW125",
  "codingRate": "4/5",
  "gwCnt": 1,
  "gwInfo": [
    {
      "gwEui": "7276FF003903002E",
      "rfRegion": "EU868",
      "rssi": -60,
      "snr": 9,
      "channel": 7,
      "radioId": 1
    }
  ]
}
</code>

==== Mapping table ====

For your convenience, here is the mapping from/to the old/new API:

^ Field                                              ^ API v3.x                       ^ API v2.3                       ^
| message identifier                                 | ''.id''                        |                                |
| end device information                             | ''.endDevice''                 |                                |
| device EUI                                         | ''.endDevice.devEui''          | ''.devEui''                    |
| device address                                     | ''.endDevice.devAddr''         |                                |
| cluster information                                | ''.endDevice.cluster''         |                                |
| cluster identifier                                 | ''.endDevice.cluster.id''      |                                |
| frame port                                         | ''.fPort''                     | ''.userdata.fPort''            |
| frame counter downlink                             | ''.fCntDown''                  | ''.fcntDown''                  |
| frame counter uplink                               | ''.fCntUp''                    | ''.fcntUp''                    |
| ADR activated?                                     | ''.adr''                       | ''.moteTx.adr''                |
| Acknowledgement required?                          | ''.confirmed''                 |                                |
| Is payload encrypted?                              | ''.encrypted''                 |                                |
| Payload                                            | ''.payload''                   | ''.userdata.payload''          |
| Receive time (ms)                                  | ''.recvTime''                  |                                |
| Gateway Receive time (ms)                          | ''.gwRecvTime''                |                                |
| Uplink frequency                                   | ''.ulFrequency''               | ''.moteTx.freq''               |
| Uplink modulation                                  | ''.modulation''                | ''.moteTx.modu''               |
| Uplink data rate                                   | ''.dataRate''                  | ''.moteTx.datr''               |
| Uplink coding rate                                 | ''.codingRate''                | ''.moteTx.codr''               |
| Gateway count                                      | ''.gwCnt''                     |                                |
| Gateways information                               | ''.gwInfo''                    | ''.gwRx''                      |
| Gateway EUI                                        | ''.gwInfo[].gwEui''            | ''.gwRx[].eui''                |
| Gateway RF region                                  | ''.gwInfo[].rfRegion''         |                                |
| Gateway RSSI                                       | ''.gwInfo[].rssi''             | ''.gwRx[].rssic/rssi''         |
| Gateway SNR                                        | ''.gwInfo[].snr''              | ''.gwRx[].lsnr''               |
| Gateway channel number                             | ''.gwInfo[].channel''          | ''.gwRx[].chan''               |
| Gateway radio identifier                           | ''.gwInfo[].radioId''          |                                |