NETPIE REST API

NETPIE มีบริการ REST API เตรียมไว้ให้ สำหรับอุปกรณ์ที่ไม่สามารถใช้ Microgear ผ่านโพรโทคอล MQTT ในการสื่อสารได้ หรือยังไม่มี Microgear ในภาษาที่ต้องการใช้ (เช่น IPhone ที่ใช้ Objective C หรือ เว็บเซิร์ฟเวอร์ที่ใช้ PHP) ขอเพียงแค่อุปกรณ์รองรับโพรโทคอล HTTP ที่พอร์ต 80 ก็สามารถเรียกใช้ NETPIE REST API ได้ อุปกรณ์ที่ใช้ REST API สามารถแลกเปลี่ยนข้อมูลกับอุปกรณ์อื่นที่ใช้ REST API หรือกับอุปกรณ์ที่ใช้ Microgear ก็ได้ ข้อดีของการใช้ NETPIEREST API คือไม่ยึดติดกับ Programming Language ฮาร์ดแวร์และระบบปฏิบัติการ สามารถนำไปประยุกต์ใช้กับอุปกรณ์แบบดั้งเดิม (Legacy Device) ได้ ใช้งานผ่าน TCP พอร์ต 80 ซึ่งเป็นพอร์ตที่เครือข่ายทั่วไปอนุญาตให้ใช้ (ถ้าใช้ Microgear ซึ่งเป็นโพรโทคอล MQTT ต้องใช้ TCP พอร์ต 1883, 8083, และ 8080)

การพัฒนา Microgear Library ออกมาให้ครอบคลุมทุก Hardware Platform นั้นเป็นเรื่องที่เป็นไปได้ยากมาก และเป็นงานที่ใช้เวลา NETPIE จึงพัฒนา REST API ขึ้นมาเป็นอีกหนึ่งทางเลือก สำหรับ Hardware Platform ที่ NETPIE ยังไม่มี Library ไปรองรับ และรวมไปถึงระบบหรือบริการที่มีมาอยู่ก่อนแล้ว ก็สามารถเรียก API มาเชื่อมต่อ NETPIE ได้เช่นกัน

API Endpoint

REST API ของ NETPIE ให้บริการอยู่ที่https://api.netpie.io/

Authentication

ในการเชื่อมต่อ API Client จะต้องทำการยืนยันตัวตน โดยใช้หนึ่งในสองวิธีนี้

1.ส่งผ่าน HTTP Header แบบ Basic Auth โดยใช้

Username: KEY

Password: SECRET

ตัวอย่างการใช้ Basic Auth ด้วย Command Line คำสั่ง cURL

$ curl -X GET "http://www.domainname.com/resource" -u key:secret

2.ส่งผ่านทาง URL Parameter ในรูปแบบ

?auth=KEY:SECRET

ตัวอย่างการใช้ URL Parameter ด้วย CommandLine คำสั่ง cURL

$ curl -X GET "http://www.domainname.com/resources?auth=key:secret"

Resource

การใช้ REST API ของ NETPIE จะเป็นการกระทำการบางอย่างกับ Resource ซึ่ง Resource ที่เข้าถึงได้ของ NETPIE มีอยู่ 3 แบบด้วยกัน ได้แก่

1.Microgear หมายถึงตัว อุปกรณ์เอง เราสามารถ Chat ตรงไปหามันได้ โดยอ้างอิงชื่อ Alias

2.Topic เป็นสิ่งเดียวกับ Topic เวลา Publish/Subscribe เราสามารถ Publish ข้อความไปที่ Topic โดยใช้ REST API ได้เช่นกัน โดยอุปกรณ์ที่ Subscribe อยู่ก็จะได้รับข้อความTopic นั้น

3.Postbox คือถังเก็บข้อมูลชั่วคราว สามารถส่งข้อความเข้าไป หรืออ่านข้อความออกมาได้

HTTP Method

HTTP Method ที่ NETPIE REST API รองรับคือ GET(เพื่อเรียกดูข้อมูล) และ PUT(เพื่อเขียนข้อมูล)วิธีการเรียกใช้งาน

PUT

PUT /microgear/{appid}/{alias}

PUT /topic/{appid}/{topicname}

PUT /postbox/{appid}/{postboxname}

Parameter Method PUT รับ Parameter ชื่อ retain ซึ่งหากกำหนด retain จะมีความหมายว่าให้ NETPIE เก็บค่านี้ไว้ ซึ่งแพลตฟอร์มจะเก็บเฉพาะค่าล่าสุดเพียงค่าเดียว

Body ในเนื้อหา (Payload) ของ HTTP PUT จะเป็นข้อความที่ต้องการส่งไปยัง topic/microgear/postbox

ตัวอย่างการเรียกใช้งาน PUT ในการส่งข้อความ ON แบบ retain ไปยัง Topic ชื่อ mytopic ใน AppID ชื่อ myappid แบบส่ง Authentication ไปใน URL

$ curl -X PUT "https://api.netpie.io/topic/myappid/mytopic?retain&auth=MyKey:MySecret"-d "ON"

ตัวอย่างการเรียกใช้งานPUT ในการส่งข้อความ ON แบบ retain ไปยัง Topic ชื่อ mytopic ใน AppID ชื่อ myappid แบบส่ง Authentication ไปใน HTTP Header แบบ Basic Auth

$ curl -X PUT "https://api.netpie.io/topic/myappid/mytopic?retain" -d "ON" -u MyKey:MySecret

GET

GET /microgear/{appid}/{alias}

GET /topic/{appid}/{topicname}

GET /postbox/{appid}/{postboxname}

Parameter ไม่มี

Body ไม่มี

ตัวอย่างการเรียกใช้งาน GETในการอ่านข้อความใน Topic หรือ mytopic ใน AppID ชื่อ myappid แบบส่ง Authentication ไปใน URL

$ curl -X GET "https://api.netpie.io/topic/myappid/mytopic?auth=MyKey:MySecret"

ตัวอย่างการเรียกใช้งาน GET ในการอ่านข้อความใน Topic หรือ mytopic ใน AppID ชื่อ myappid แบบส่ง Authenticationไปใน HTTP Header แบบ Basic Auth

$ curl -X GET "https://api.netpie.io/topic/myappid/mytopic"-u MyKey:MySecret

เราสามารถทดสอบการเรียก Method Get โดยนำ URL ไปใส่ใน Browser โดยตรงได้เช่น
ถ้าทำงานได้ถูกต้องจะได้รับค่าที่เคย PUT และ retain ไปยัง topic/microgear/postbox นี้ ในรูปแบบ JSON เช่น

[{"topic":"/myappid/mytopic","payload":"ON","lastUpdated":1471760882,"retain":true}]