CLOUD: Update api.md

cloud/cloud-v2/api.md

@@ -1,47 +1,58 @@
 ---
 slug: api
-title: API
+title: HARDWARIO Cloud v2 REST API
 ---
 import Image from '@theme/IdealImage';
 
-# API
+# HARDWARIO Cloud v2 REST API
 
-For Cloud v2 API please see the [**API Swagger documentation**](https://api.hardwario.cloud/v2/documentation/).
+For HARDWARIO Cloud v2 REST API, please see the [**API Swagger documentation**](https://api.hardwario.cloud/v2/documentation/).
 
-For real-time delivery of devices' messages we strongly recommend using HTTP callback, please see the [**Connectors**](connectors.md).
+For real-time delivery of messages from the devices, we strongly recommend using HTTPS webhooks. The REST API polling for messages increases delivery latency, data traffic, and request load on the service. Please see the [**Connectors**](connectors.md) for more details on data passing to your API endpoint through webhooks.
 
 ## API Examples
 
-### List devices in space with cURL
+### List devices in the space with cURL
 
-Please create an API key and fill it in `<api-key>`, also set correct `<space-id>`.
+Please create an API key with appropriate permissions and replace these fields:
+
+* Field `<api-key>,`
+* Field `<space-id>`
 
 ```
-curl -X GET "https://api.hardwario.cloud/v2/spaces/<space-id>/devices" -H 'accept: application/json' -H 'X-API-Key: <api-key>' -H 'Content-Type: application/json'
+curl -X GET \
+  -H 'X-Api-Key: <api-key>' \
+  -H 'Accept: application/json' \
+  'https://api.hardwario.cloud/v2/spaces/<space-id>/devices'  
 ```
 
-### List devices in space with Python
+### List messages for a particular device with cURL
 
-```python
-#!/usr/bin/env python3
-
-import requests
-import json
+Please create an API key with appropriate permissions and replace these fields:
 
-api_key = ...
-space_id = ...
-base_url = 'https://api.hardwario.cloud'
+* Field `<api-key>,`
+* Field `<space-id>`
+* Field `<device-id>`
+* Field `<offset>` (UUID of the last read message; optional/irrelevant for the first listing)
 
+```
+curl -X GET \
+  -H 'X-Api-Key: <api-key>' \
+  -H 'Accept: application/json' \
+  'https://api.hardwario.cloud/v2/spaces/<space-id>/messages?device_id=<device-id>&offset=<offset>'
+```
 
-def get_devices():
-    data = requests.get(f'{base_url}/v2/spaces/{space_id}/devices?limit=500',
-                        headers={'X-API-Key': api_key}).json()
+### List devices in space with Python
 
-    for item in data:
-        print(item["id"], item["name"])
+```python
+import requests
 
+api_key = '...'
+space_id = '...'
 
-if __name__ == "__main__":
-    get_devices()
+data = requests.get(f'https://api.hardwario.cloud/v2/spaces/{space_id}/devices?limit=500',
+                    headers={'X-Api-Key': api_key}).json()
 
+for item in data:
+    print(item['id'], item['name'])
 ```