Add documentation for analytics API

3 files changed, 85 insertions, 2 deletions

diff --git a/app/Http/Controllers/Api/ApiAnalyticsController.php b/app/Http/Controllers/Api/ApiAnalyticsController.php
index 8e4bc7e..2efc4c2 100644
--- a/app/Http/Controllers/Api/ApiAnalyticsController.php
+++ b/app/Http/Controllers/Api/ApiAnalyticsController.php
@@ -8,7 +8,7 @@ use App\Helpers\StatsHelper;
 
 class ApiAnalyticsController extends ApiController {
     public function lookupLinkStats (Request $request, $stats_type=false) {
-        $response_type = $request->input('response_type');
+        $response_type = $request->input('response_type') ?: 'json';
 
         if ($response_type != 'json') {
             abort(401, 'Only JSON-encoded data is available for this endpoint.');
diff --git a/docs/css/base.css b/docs/css/base.css
index 7a4af72..3183ecd 100644
--- a/docs/css/base.css
+++ b/docs/css/base.css
@@ -11,3 +11,9 @@ img {
     width: auto !important;
     height: auto !important;
 }
+
+code:not(.hljs) {
+    /* Do not wrap pre-formatted code snippets */
+    word-wrap: break-word;
+    white-space: normal;
+}
diff --git a/docs/developer-guide/api.md b/docs/developer-guide/api.md
index ccad048..c7f854b 100644
--- a/docs/developer-guide/api.md
+++ b/docs/developer-guide/api.md
@@ -29,6 +29,9 @@ The Polr API will reply in `plain_text` or `json`. The response type can be
 set by providing the `response_type` argument to the request. If not provided,
 the response type will default to `plain_text`.
 
+Data endpoints will only return JSON-formatted data and will default to `json` if no
+`response_type` is provided.
+
 Example `json` responses:
 ```
 {
@@ -72,6 +75,7 @@ Arguments:
 Response: A JSON or plain text representation of the shortened URL.
 
 Example: GET `http://example.com/api/v2/action/shorten?key=API_KEY_HERE&url=https://google.com&custom_ending=CUSTOM_ENDING&is_secret=false`
+
 Response:
 ```
 {
@@ -95,6 +99,7 @@ Arguments:
 Remember that the `url` argument must be URL encoded.
 
 Example: GET `http://example.com/api/v2/action/lookup?key=API_KEY_HERE&url_ending=2`
+
 Response:
 ```
 {
@@ -103,6 +108,77 @@ Response:
 }
 ```
 
+### /api/v2/data/link
+Arguments:
+
+ - `url_ending`: the link ending for the URL to look up. (e.g `5ga`)
+ - `left_bound`: left date bound (e.g `2017-02-28 22:41:43`)
+ - `right_bound`: right date bound (e.g `2017-03-13 22:41:43`)
+ - `stats_type`: the type of data to fetch
+    - `day`: click counts for each day from `left_bound` to `right_bound`
+    - `country`: click counts per country
+    - `referer`: click counts per referer
+
+The dates must be formatted for the `strtotime` PHP function and must be parsable by Carbon.
+By default, this API endpoint will only allow users to fetch a maximum of 365 days of data. This setting
+can be modified in the `.env` configuration file.
+
+An API key granted to a regular user can only fetch data for their own links.
+Admins can fetch data for any link.
+
+Response: A JSON representation of the requested analytics data.
+
+Example: GET `http://example.com/api/v2/data/link?stats_type=day&key=API_KEY_HERE&url_ending=5gk&response_type=json&left_bound=2017-02-28%2022:41:43&right_bound=2017-03-13%2022:21:43`
+
+Response:
+```
+{
+    "action":"data_link_day",
+    "result": {
+        "url_ending":"5gk",
+        "data": [
+            {"x":"2017-03-10","y":42},
+            {"x":"2017-03-11","y":1},
+            {"x":"2017-03-12","y":5}
+        ]
+    }
+}
+```
+
+Example: GET `http://example.com/api/v2/data/link?stats_type=country&key=API_KEY_HERE&url_ending=5gk&response_type=json&left_bound=2017-02-28%2022:41:43&right_bound=2017-03-13%2022:21:43`
+
+Response:
+```
+{
+    "action":"data_link_day",
+    "result": {
+        "url_ending":"5gk",
+        "data": [
+            {"label":"FR","clicks":1},
+            {"label":"US","clicks":6},
+            {"label":"CA","clicks":41}
+        ]
+    }
+}
+```
+
+Example: GET `http://example.com/api/v2/data/link?stats_type=country&key=API_KEY_HERE&url_ending=5gk&response_type=json&left_bound=2017-02-28%2022:41:43&right_bound=2017-03-13%2022:21:43`
+
+Response:
+```
+{
+    "action":"data_link_day",
+    "result": {
+        "url_ending":"5gk",
+        "data": [
+            {"label":"Direct","clicks":6},
+            {"label":"reddit.com","clicks":12},
+            {"label":"facebook.com","clicks":30}            
+        ]
+    }
+}
+```
+
 ## HTTP Error Codes
 The API will return an error code if your request was malformed or another error occured while processing your request.
 
@@ -152,4 +228,5 @@ Example `plain_text` error response:
 
 ## Testing the API
 
-You may test your integrations on http://demo.polr.me with the credentials "demo-admin"/"demo-admin". Keep in mind the instance is only a demo and may be cleared at any time.
+You may test your integrations on http://demo.polr.me with the credentials "demo-admin"/"demo-admin".
+The demo instance is reset every day.