├── README.md └── README.th.md /README.md: -------------------------------------------------------------------------------- 1 | # microgear-restapi 2 | 3 | NETPIE platform prepares the REST API for connecting to other devices thru the HTTP protocol. This API is programming language independent. It can be used with traditional web server, through command lines or or through web services. 4 | 5 | ### API Endpoint 6 | NETPIE's REST API service is at 7 | 8 | ``` 9 | https://api.netpie.io/ 10 | ``` 11 | 12 | ### Authentication 13 | To connect to NETPIE, the API client has to authenticate itself using one of these two methods. 14 | 15 | 1. Basic Authentication through the HTTP Header, using 16 | ``` 17 | Username : APPKEY 18 | Password : APPSECRET 19 | ``` 20 | Example of Basic Authentication with cURL 21 | ``` 22 | $ curl -X GET "http://www.domainname.com/resources" -u john:secret 23 | ``` 24 | 2. Authenticate via URL parameter, using 25 | ``` 26 | ?auth=APPKEY:APPSECRET 27 | ``` 28 | Example of URL parameter with cURL 29 | ``` 30 | $ curl -X GET "http://www.domainname.com/resources?auth=john:secret" 31 | ``` 32 | --- 33 | ### Resource Types 34 | #### Topic 35 | Topic is the location for mesage exchange among microgears. Topic name has a path format, for example, /home/bedroom/temp. Microgear can PUT/publish, GET/subscribe to this topic. 36 | 37 | #### Microgear 38 | Microgear is the device that connects to NETPIE. We can send a message directly to any microgears by addressing their alias. 39 | #### Postbox 40 | postbox is the message storage location. Messages are stored in postbox as queue (first in, first out) until they are read. Read messages will be removed from postbox. It is suitable for microgear that cannot have real-time communication like PHP script. 41 | 42 | --- 43 | 44 | 45 | #### topic 46 | -- 47 | **PUT /topic/**_{appid}_**/**_{topic}_ 48 | 49 | publish message to the topic of a specified appid 50 | 51 | URL parameter 52 | * *retain* Keep this message (only keep the newest message) 53 | 54 | Body 55 | * message to publish. If you want to remove the previous retained message, set the retain parameter as True and send an empty-string message. 56 | 57 | Example of calling REST API with cURL 58 | Suppose we have an application on NETPIE with appid = myappid and App Key and App Secret are as follows. 59 | ![myappid-sample](https://cloud.githubusercontent.com/assets/7685964/11860526/509ed20a-a4a8-11e5-9bda-43749e256e70.png) 60 | 61 | We will use REST API to send a retained message "ON" to a microgear that subscribes topic /home/bedroom/light using this cURL command line 62 | ``` 63 | $ curl -X PUT "https://api.netpie.io/topic/myappid/home/bedroom/light?retain" -d "ON" -u jVjzJXaJwdJKHhF:StOAKIZhXB5CaqnIHeb7s1DfiW7mQj 64 | ``` 65 | -- 66 | **GET /topic/**_{appid}_**/**_{topic}_ 67 | 68 | Read message from a topic of a specified appid. Client will only receive the newest retained message. 69 | 70 | URL parameter 71 | * None 72 | 73 | Body 74 | * None 75 | 76 | Example 77 | ``` 78 | $ curl -X GET "https://api.netpie.io/topic/myappid/home/bedroom/light" -u jVjzJXaJwdJKHhF:StOAKIZhXB5CaqnIHeb7s1DfiW7mQj 79 | ``` 80 | 81 | --- 82 | #### Microgear 83 | 84 | **PUT /microgear/**_{appid}_**/**_{gearalias}_ 85 | 86 | Send a message to a microgear of the appid *appid* whose alias is *gearalias* 87 | 88 | Body 89 | * message to be sent as a plain text string. If the message is encoded as JSON, the receiver has to parse the string by itself. 90 | 91 | --- 92 | #### Push Notification 93 | 94 | **PUT /push/owner** 95 | 96 | Send a push notification to an AppID owner via a NETPIE mobiele app. 97 | 98 | Body 99 | * message to be sent as a plain text string. 100 | 101 | --- 102 | #### Postbox 103 | 104 | **PUT /postbox/**_{appid}_**/**_{postboxname}_ 105 | 106 | Send a message to a postbox named *postboxname* that belongs to an *appid* 107 | 108 | URL parameter 109 | * *tag* Sender can set a tag to a message. This tag can be use to select messages of interest. 110 | 111 | Body 112 | * message to be sent as a plain text string. If the message is encoded as JSON, the receiver has to parse the string by itself. 113 | ``` 114 | $ curl -X PUT "https://api.netpie.io/postbox/myappid/webbox?tag=error" -d "ON" -u jVjzJXaJwdJKHhF:StOAKIZhXB5CaqnIHeb7s1DfiW7mQj 115 | ``` 116 | -- 117 | **GET /postbox/**_{appid}_**/**_{postboxname}_ 118 | 119 | Read a message one message at a time from the postbox named *postboxname* that belongs to an *appid*. The message that arrives first will be read out first. 120 | 121 | URL parameter 122 | * *tag* Don't need to be specified. If a tag is specified, only the messages with that tag will be read out. 123 | 124 | Body 125 | * None 126 | ``` 127 | $ curl -X GET "https://api.netpie.io/postbox/myappid/webbox?tag=error" -u jVjzJXaJwdJKHhF:StOAKIZhXB5CaqnIHeb7s1DfiW7mQj 128 | ``` 129 | -------------------------------------------------------------------------------- /README.th.md: -------------------------------------------------------------------------------- 1 | # microgear-restapi 2 | 3 | NETPIE platform ได้จัดเตรียม REST API สำหรับการติดต่อสื่อสารกับ microgear ชนิดอื่นๆ ผ่านทาง HTTP protocol ที่เข้าถึงได้ง่าย โดยไม่ยึดติดกับ programming language หรือ hardware สามารถนำไปประยุกต์ใช้กับ web server แบบดั้งเดิม หรือเรียกผ่าน command line รวมไปถึงการเชื่อมต่อกับ web service ต่างๆ 4 | 5 | 6 | ### API Endpoint 7 | REST API ของ NETPIE ให้บริการอยู่ที่ 8 | 9 | ``` 10 | https://api.netpie.io/ 11 | ``` 12 | 13 | ### Authentication 14 | ในการเชื่อต่อ API client จะต้องทำการยืนยันตัวตน โดยใช้หนึ่งในสองวิธีนี้ 15 | 16 | 1. ส่งผ่าน HTTP Header แบบ Basic Auth โดยใช้ 17 | ``` 18 | Username : APPKEY 19 | Password : APPSECRET 20 | ``` 21 | ตัวอย่างการใช้ Basic Auth ด้วย cURL 22 | ``` 23 | $ curl -X GET "http://www.domainname.com/resources" -u john:secret 24 | ``` 25 | 3.2.ส่งผ่านทาง URL parameter ในรูปแบบ 26 | ``` 27 | ?auth=APPKEY:APPSECRET 28 | ``` 29 | ตัวอย่างการใช้ URL parameter ด้วย cURL 30 | ``` 31 | $ curl -X GET "http://www.domainname.com/resources?auth=john:secret" 32 | ``` 33 | --- 34 | ### Resource Types 35 | #### Topic 36 | topic เป็นจุดแลกเปลี่ยน message ระหว่าง microgear ลักษณะการเขียนจะอยู่ในรูปของ path เช่น /home/bedroom/temp โดย microgear สามารถ PUT/publish, GET/subscribe ไปที่ topic นี้ได้ 37 | 38 | #### Microgear 39 | microgear คือ device ที่เชื่อมต่อกับ NETPIE เราสามารถสื่อสารตรงไปที่ microgear โดยอ้างอิงชื่อ alias ที่ตั้งให้ device นั้น 40 | 41 | #### Postbox 42 | postbox เป็นพื้นที่สำหรับเก็บข้อมูลแบบ queue โดย message ที่ถูกส่งเข้าไปใน postbox จะถูกเก็บสะสมไว้ จนกว่าจะมีการอ่านออกไป message ที่ถูกอ่านแล้วจะหายไปจาก postbox ทันที เหมาะที่จะใช้เป็นเครื่องมือสื่อสารกับ microgear ที่ไม่สามารถ online ได้ตลอดเวลา เช่น PHP script 43 | 44 | --- 45 | #### topic 46 | -- 47 | **PUT /topic/**_{appid}_**/**_{topic}_ 48 | 49 | publish message ไปยัง topic ของ appid ตามที่ระบุ 50 | 51 | URL parameter 52 | * *retain* สั่งให้เก็บค่านี้ไว้ (เฉพาะค่าล่าสุดเพียงค่าเดียว) 53 | 54 | Body 55 | * เป็น message ที่จะส่ง หากต้องการลบค่าที่ retain ไว้ ให้ส่งแบบ retain และใช้ body เป็น string เปล่า 56 | 57 | ตัวอย่างการเรียก REST API ด้วย cURL สมมติว่าเราได้สร้าง App บน NETPIE ชื่อ myappid และมี Key และ Secret ดังนี้ 58 | ![myappid-sample](https://cloud.githubusercontent.com/assets/7685964/11860526/509ed20a-a4a8-11e5-9bda-43749e256e70.png) 59 | 60 | เราจะใช้ REST API ในการส่ง message แบบ retain ว่า "ON" ไปยัง microgear ที่ subscribe topic /home/bedroom/light ได้ด้วย cURL command line นี้ 61 | ``` 62 | $ curl -X PUT "https://api.netpie.io/topic/myappid/home/bedroom/light?retain" -d "ON" -u jVjzJXaJwdJKHhF:StOAKIZhXB5CaqnIHeb7s1DfiW7mQj 63 | ``` 64 | -- 65 | **GET /topic/**_{appid}_**/**_{topic}_ 66 | 67 | อ่าน message จาก appid ที่ topic ตามที่ระบุ client จะได้รับเฉพาะ message ล่าสุดที่ถูก retain ไว้ก่อนหน้านี้ 68 | 69 | URL parameter 70 | * ไม่มี 71 | 72 | Body 73 | * ไม่มี 74 | 75 | ตัวอย่าง 76 | ``` 77 | $ curl -X GET "https://api.netpie.io/topic/myappid/home/bedroom/light" -u jVjzJXaJwdJKHhF:StOAKIZhXB5CaqnIHeb7s1DfiW7mQj 78 | ``` 79 | 80 | --- 81 | #### Microgear 82 | 83 | **PUT /microgear/**_{appid}_**/**_{gearalias}_ 84 | 85 | ส่ง message ไปยัง microgear ที่ตั้งชื่อว่า *gearalias* ของ appid *appid* 86 | 87 | Body 88 | * message ที่จะส่ง เป็น plain text string หากมีการ encode ด้วยรูปแบบ json ทางปลายทางจะต้องนำ string ไป parse เอง 89 | 90 | 91 | --- 92 | #### Push Notification 93 | 94 | **PUT /push/owner/** 95 | 96 | ส่ง message ไปยังเจ้าของ AppID ผ่านทางโมบายแอป NETPIE 97 | 98 | Body 99 | * message ที่จะส่ง เป็น plain text string 100 | 101 | ``` 102 | $ curl -X PUT "https://api.netpie.io/push/owner" -d "The temperature is too high!" -u jVjzJXaJwdJKHhF:StOAKIZhXB5CaqnIHeb7s1DfiW7mQj 103 | ``` 104 | 105 | --- 106 | #### Postbox 107 | 108 | **PUT /postbox/**_{appid}_**/**_{postboxname}_ 109 | 110 | ส่ง message ไปยัง postbox ชื่อ *postboxname* ของ *appid* 111 | 112 | URL parameter 113 | * *tag* ผู้ส่งสามารถติด tag ให้ message ได้ เพื่อความสะดวกในการเลือกอ่านเฉพาะ message ที่สนใจ 114 | 115 | Body 116 | * message ที่จะส่ง เป็น plain text string หากมีการ encode ด้วยรูปแบบ json ทางปลายทางจะต้องนำ string ไป parse เอง 117 | ``` 118 | $ curl -X PUT "https://api.netpie.io/postbox/myappid/webbox?tag=error" -d "ON" -u jVjzJXaJwdJKHhF:StOAKIZhXB5CaqnIHeb7s1DfiW7mQj 119 | ``` 120 | -- 121 | **GET /postbox/**_{appid}_**/**_{postboxname}_ 122 | 123 | อ่าน message ครั้งละหนึ่ง message จาก postbox ชื่อ *postboxname* ของ *appid* โดยจะเรียงตามลำดับเวลา message ที่เข้ามาก่อน จะถูกอ่านก่อน 124 | 125 | URL parameter 126 | * *tag* ไม่จำเป็นต้องระบุ แต้หากมีการระบุ tag จะเป็นการเจาะจงอ่านเฉพาะ message ที่ติด tag นั้นเท่านั้น 127 | 128 | Body 129 | * ไม่มี 130 | ``` 131 | $ curl -X GET "https://api.netpie.io/postbox/myappid/webbox?tag=error" -u jVjzJXaJwdJKHhF:StOAKIZhXB5CaqnIHeb7s1DfiW7mQj 132 | ``` 133 | --------------------------------------------------------------------------------