Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision 		Previous revision
en:protocole_json [2014/05/20 00:29]
naguirre created 		en:protocole_json [2021/09/16 21:39] (current)
mifrey [In url with HTTP GET]
Line 1: Line 1:
 ====== Calaos Webservice protocol ====== ====== Calaos Webservice protocol ======
  
-Calaos server has a communication protocol base on HTTP requests. Data exchanged are formated in the [[http://fr.wikipedia.org/wiki/Json|JSON]] format.+Calaos server has a communication protocol based on HTTP requests. Data exchanged are formatted in the [[http://fr.wikipedia.org/wiki/Json|JSON]] format.
  
 ===== Requests details ===== ===== Requests details =====
  
-Requests are made via HTTPS directly on calaos server. Requests have the following URL ::+Requests are made via HTTPS directly on calaos server. Requests have to be done on the following URL :
  
   https://calaos_server_ip/api.php   https://calaos_server_ip/api.php
Line 11: Line 11:
 ===== Testing ===== ===== Testing =====
  
-It's possible to test the API with command line utils like [[http://en.wikipedia.org/wiki/Wget|Wget]] or [[http://en.wikipedia.org/wiki/CURL|cURL]]+==== Wget ==== 
 +It is possible to test the API using command line tools like [[http://en.wikipedia.org/wiki/Wget|Wget]] or [[http://en.wikipedia.org/wiki/CURL|cURL]]
  
-==== Wget Example ====+Data in JSON format are placed in the file //query.json//. The resulting file will then be //result.json//.
  
-Data to be sent has the JSON format and are places in the file //query.json//. The resulting file will be then //result.json//.+  wget --no-check-certificate --post-file query.json --output-document result.json https://calaos_server_ip/api.php 
 +   
 +==== In url with HTTP GET ====
  
-  wget --no-check-certificate --post-file query.json --output-document result.json https://ip_address/api.php+The requests must be made with HTTP POST with Calaos v2.  Calaos v3 also supports HTTP GET and it is therefore possible to send a request directly in the url.
  
-==== Wget Example ====+Examples: 
 +  * Get the config: https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=get_home 
 +  * Get a picture from a camera: https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=camera&type=get_picture&id=input_57_output_32 
 +  * Set an output: https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=set_state&id=output_7&value=true 
 +  * Set an intern variable: https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=set_state&id=intern_4&value=true 
 +  * Read a variable : https://calaos_server_ip/api?cn_user=XXX&cn_pass=XXX&action=get_state&items=output_21,output_25
  
-TBC+That allows an external system that only supports HTTP GET to easily communicate to Calaos. 
 + 
 +==== HTML Page ==== 
 + 
 +Calaos v3 includes a debug web page to test the POST and Websocket requests.  It allows to easily verify the format of the JSON data to send. 
 + 
 +We need first to activate the debug mode with following command: 
 +<code> 
 +calaos_config set debug_enabled true 
 +</code> 
 +or directly add it in the file ///etc/calaos/local_config.xml//. 
 + 
 +The page is then accessible from https://calaos_server_ip/debug or http://calaos_server_ip:5454/debug . 
 + 
 +{{ :fr:api_debug_html.png?nolink&600 |}} 
 + 
 +==== Use the API with other languages ==== 
 + 
 +  * [[json_python2|Python 2]] 
 +  * [[json_python3|Python 3]]
  
 ===== API Calaos Network ===== ===== API Calaos Network =====
Line 33: Line 60:
 With this command you can get the complete configuration of the house. With this command you can get the complete configuration of the house.
  
-=== Exeaple ===+=== Example ===
  
-Json Data to be send :+Json Data to be sent :
   {   {
       "cn_user": "mail@example.com",       "cn_user": "mail@example.com",
Line 152: Line 179:
   }   }
      
-The answer give us 3 arrays wich represent the configuration of the house ["home"], the list of cameras ["camera"] and the audio zones ["audio"]. All these informations has the same type of what is sent by [[protocole_tcp|the TCP Protocole]].+The answer gives us 3 arrays which represents the configuration of the house ["home"], the list of cameras ["camera"] and the audio zones ["audio"]. All those information have the same type as in the [[protocole_tcp|TCP Protocol]].
  
 ==== get_state ==== ==== get_state ====
  
-This command may be used to get the state of one or many Input/Output and the state of the music zones. Parameters included are the ID of the I/O as find in the [[protocole_tcp|the TCP Protocol]].+This command may be used to get the state of one or many Input/Output and the state of the music zones. Parameters included are the ID of the I/O as found in the [[protocole_tcp|TCP Protocol]].
  
-=== Exeample ===+=== Example ===
  
-JSON Data to be send+JSON Data to be sent
   {   {
       "cn_user": "mail@example.com",       "cn_user": "mail@example.com",
Line 199: Line 226:
 } }
  
-The answer contains the list of I/O asked and the values of the states.+Answer contains the list of queried I/O and their state value.
  
 ==== set_state ==== ==== set_state ====
  
-This command is used to change the state of one or many I/O. Parameters contains the ID of I/o, those found in the [[protocole_tcp|the TCP Protocole]]. +This command is used to change the state of one or many I/O. Parameters contains the ID of I/O, as in the [[protocole_tcp|TCP Protocol]]. 
  
-=== Exemple ===+=== Example ===
  
-JSON data to be send :+JSON data to be sent :
   {   {
       "cn_user": "mail@example.com",       "cn_user": "mail@example.com",
Line 223: Line 250:
   }   }
  
-If you want to force the value of an input, you can chante the type by :+If you want to force the value of an input, you need to set type to "input" :
   "type": "input"   "type": "input"
      
-Command may also be sent to the music zone. Those commande are the same found in the [[protocole_tcp|the TCP Protocole]].+Command may also be sent to the music zones. Those commands are the same as in the [[protocole_tcp|TCP Protocol]].
  
-=== Exemple ===+=== Example ===
  
-JSON Data to be send :+JSON Data to be sent :
   {   {
       "cn_user": "mail@example.com",       "cn_user": "mail@example.com",
Line 240: Line 267:
   }   }
  
-We can also send data to a motorised camera. Commands are the same as those found in the [[protocole_tcp|the TCP Protocole]].+We can also send data to a camera with PTZ control. Commands are the same as in the [[protocole_tcp|TCP Protocol]].
  
 === Example === === Example ===
  
-JSON Data to be send :+JSON Data to be sent :
   {   {
       "cn_user": "mail@example.com",       "cn_user": "mail@example.com",
Line 261: Line 288:
 === Example === === Example ===
  
-Données JSON à envoyer:+JSON Data to be sent :
   {   {
       "cn_user": "mail@example.com",       "cn_user": "mail@example.com",
Line 269: Line 296:
   }   }
  
-You can alos add the parameters //from// et //to// to specify a part ot the playlist to load. This can be usefull in case of asynchronous uses or when the playlist is big.+You can also add the parameters //from// and //to// to specify a part of the playlist to load. This can be useful in case of asynchronous uses or when the playlist is big.
  
 Answer: Answer:
Line 302: Line 329:
 } }
  
-The answer contains the list of tracks and more informations id they are available, like artist, album, title, ...+The answer contains the list of tracks with all their information like id, artist, album, title, ...
  
 ==== poll_listen ==== ==== poll_listen ====
  
-This command is used to monitor all the changes of an IO of the server. Each call will get only changes. You need to register first to get a unique id, and the server will notify you each time a change occurs on the specified I/O+This command is used to monitor all the changes of an IO of the server. Every call will get only changes. You need first to register and get a unique id, and the server will notify you each time a change occurs on the specified I/O
  
 === Register === === Register ===
  
-To register and get an unique ID, you have to send the following request :+To register and get a unique ID, you have to send the following request :
   {   {
       "cn_user": "mail@example.com",       "cn_user": "mail@example.com",
Line 323: Line 350:
   }   }
  
-This ID is unique and is valid as long as you used it. If it's not used, it becomes invalide after 5 min.+This ID is unique and is valid as long as you used it. If not used within 5 min, it becomes invalid.
  
 === Remove === === Remove ===
-When you have finished listening changes on an IO, you can remove this ID. Deleting an ID is not mandatory, as it's always done after 5min on inactivity. 
  
-JSON Data to be send :+When you have finished listening changes on an IO, you can remove this ID. Deleting an ID is not mandatory, as it's always done after 5 min on inactivity. 
 + 
 +JSON Data to be sent :
   {   {
       "cn_user": "mail@example.com",       "cn_user": "mail@example.com",
Line 344: Line 372:
 === Get Events === === Get Events ===
  
-Once the registration is done and you get an unique ID, you can ask the server periodically to know what happens on this IO. The answer are the same as those sent by the //listen// command of [[protocole_tcp|the TCP Protocole]].+Once the registration is done and you have your unique ID, you can ask the server periodically to know what happens. The answer are the same as those sent by the //listen// command in the [[protocole_tcp|TCP Protocol]].
  
-JSON Data to be send:+JSON Data to be sent:
   {   {
       "cn_user": "mail@example.com",       "cn_user": "mail@example.com",
Line 371: Line 399:
 === get === === get ===
  
-To retrieve the whole config you can use the following request :+To retrieve the whole config you need to use the following request :
   {   {
       "cn_user": "mail@example.com",       "cn_user": "mail@example.com",
Line 390: Line 418:
 === put === === put ===
  
-To send the configuration on the server you can use the following request+To send the configuration on the server you need to use the following request
   {   {
       "cn_user": "mail@example.com",       "cn_user": "mail@example.com",