EDIT readme and ADD examples

WOOSEUNGHOON · WOOSEUNGHOON · commit 3e712c54777c · 2018-10-15T22:31:10.000+09:00
diff --git a/README.md b/README.md
@@ -1 +1,63 @@
-API Document
+Document for IoTcube API
+========================
+This document is an outline and usage document of "IoTcube API". This document is an early version and describes the APIs that deal with the "Vulnerable Code Clone Detection" functionality of "Whitebox Testing" in IoTcube.
+
+Getting Started with API
+------------------------
+Currently, the initial version of IoTcube API can receive vulnerability information in software by sending ".hidx file" (generated through *hmark*, <https://github.com/iotcube/hmark>) through **POST** method to our API address.
+
+**Address to send POST request**
+>**https://<span></span>iotcube.net/api/wf1**
+
+**Params**
+* ***files***: the **path** and **contents** of the ".hidx file" (which you want to check for vulnerabilities).
+* ***headers***: your **user-agent** value
+
+**Return Field Definitions**
++ **Common value**
+   + **total_cve** - Total number of detected CVEs.
+   + **total_vulfunc** - Total number of detected vulnerable functions.
+   + **file_count** - Total number of files in uploaded '.hidx file'.
+   + **func_count** - Total number of functions in uploaded '.hidx file'.
+   + **line_count** - Total number of lines in uploaded '.hidx file'.
+   
++ **Vulnerability exists**
+   + **cveid** - The CVE value of the vulnerability.
+   + **cwe** - The CWE value of the vulnerability.
+   + **cvss** - The CVSS value of the vulnerability.
+   + **file** - The file path where the vulnerability exists.
+   + **funcid** - The function number in the file (*See hmark*).
+   + **diff** - Patch information for this vulnerability.
+  
+Result (JSON)
+-------------
+```
+[
+  {
+    "total_cve"    : 5,
+    "total_vulfunc": 6, 
+    "file_count"   : 100,
+    "func_count"   : 1000,
+    "line_count"   : 10000,
+  }, 
+  {
+    "cveid" : "CVE-2018-0000",
+    "cwe"   : "CWE-119",
+    "cvss"  : "10.0", 
+    "file"  : "Path/to/file",
+    "funcid": "5",
+    "diff"  : "https://iotcube.net/whitebox/diff/.../CVE-2018-0000_....diff", 
+  }, &hellip; ,
+  {
+    &hellip; 
+  }
+] 
+```
+Sample codes
+------------
+See *'example'* directory.
+
+About
+-----
+This document and code is authored and maintained by Seunghoon Woo.
+>seunghoonwoo@<span></span>korea.ac.kr
diff --git a/example/API_example_php.php b/example/API_example_php.php
@@ -0,0 +1,26 @@
+<?php
+function CallAPI($method, $url, $header, $data)
+{
+  $curl = curl_init($url);
+  switch ($method)
+  {
+    case "POST":
+      curl_setopt($curl, CURLOPT_POST, 1);
+      if ($data)
+        curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
+      break;
+  }
+  curl_setopt($curl, CURLOPT_URL, $url);
+  curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
+  curl_setopt ($curl, CURLOPT_HTTPHEADER, $header);
+  $result = curl_exec($curl);
+  curl_close($curl);
+  return $result;
+}
+
+$file_name = "/filepath/to/hidxfile.hidx";
+$header = array ("User-Agent: your user-agent value");
+$data = array ("file" => curl_file_create (realpath($file_name)));
+$url = 'https://iotcube.net/api/wf1';
+$resp = CallAPI ("POST", $url, $header, $data);
+?>
diff --git a/example/API_example_python.py b/example/API_example_python.py
@@ -0,0 +1,5 @@
+import requests
+
+files = {'file': ("/filepath/to/hidxfile.hidx", open("/filepath/to/hidxfile.hidx", 'rb'))}
+headers = {'user-agent': 'your user-agent value'
+response = requests.post("https://iotcube.net/api/wf1", files=files, headers=headers)
