Merge pull request #161 from jaxxstorm/master

API Docs

INSTALL.md

@@ -10,6 +10,7 @@ You need at least PHP >= 5.4, [Composer](https://getcomposer.org/) and the follo
   - `php-xml`
   - `php-pdo`
   - A database driver for your DB, such as `php-mysql`
+  - `OpenSSL`
 
 # Table of contents
 

docs/api/components.md

@@ -0,0 +1,78 @@
+# API Components
+
+## `/components`
+
+Interact with components
+
+Example URL: `http://status.cachethq.io/api/components`
+
+* `GET`: returns a list of the current components and their status
+  - success: 200:
+  
+    ~~~json
+    {
+      "data": [
+        {
+        "updated_at": 1420029799,
+        "created_at": 1420029577,
+        "incident_count": 0,
+        "status": "Operational",
+        "status_id": 1,
+        "description": "This is an example component",
+        "name": "Example Component",
+        "id": 5
+        },
+        {
+        "updated_at": 1420037024,
+        "created_at": 1420037024,
+        "incident_count": 0,
+        "status": "Major Outage",
+        "status_id": 4,
+        "description": "This is a second example component",
+         "name": "Second Example Components",
+        "id": 2
+        }
+      ]
+    }
+    ~~~
+
+* `POST`: Create a component
+  - payload
+
+    ~~~json
+    {
+    "name":"Example Created API",
+    "description":"API Created",
+    "status":2
+    }
+    ~~~
+
+
+
+## `/components/:id`
+
+Show a single component
+
+Example URL: `http://status.cachethq.io/api/components/1`
+
+* `GET`: Return a single component and its status
+  - success: 200:
+
+    ~~~json
+    {
+      "data": [
+        {
+        "updated_at": 1420029799,
+        "created_at": 1420029577,
+        "incident_count": 0,
+        "status": "Operational",
+        "status_id": 1,
+        "description": "SelfServe automation tool for project publishes, resets and Operations tasks",
+        "name": "SelfServe",
+        "id": 1
+        }
+      ]
+    }
+    ~~~
+
+

docs/api/incidents.md

@@ -0,0 +1,76 @@
+# API Incidents
+
+## `/incidents`
+
+Interact with incidents
+
+Example URL: `http://status.cachethq.io/api/incidents`
+
+* `GET`: returns a list of the current incidents and their status
+  - success: 200:
+  
+    ~~~json
+  {
+  "data": [
+      {
+        "updated_at": 1420036705,
+        "created_at": 1420036705,
+        "component": null,
+        "human_status": "Investigating",
+        "status": 1,
+        "message": "This is an example incident",
+        "name": "Example Incident",
+        "id": 6
+      },
+      {
+        "updated_at": 1420038898,
+        "created_at": 1420038898,
+        "component": null,
+        "human_status": "Fixed",
+        "status": 4,
+        "message": "This is a resolved incident",
+        "name": "A resolved incident",
+        "id": 7
+      }
+    ]
+  }
+    ~~~
+
+* `POST`: Create an incident
+  - payload
+
+    ~~~json
+    {
+    "name":"Example Created Incident",
+    "message":"Description for an API created incident",
+    "status":2
+    }
+    ~~~
+
+
+
+## `/incidents/:id`
+
+Show a single incident
+
+Example URL: `http://status.cachethq.io/api/incident/1`
+
+* `GET`: Return a single incident and its status
+  - success: 200:
+
+    ~~~json
+    {
+      "data": {
+        "updated_at": 1420038898,
+        "created_at": 1420038898,
+        "component": null,
+        "human_status": "Fixed",
+        "status": 4,
+        "message": "This is a resolved incident",
+        "name": "A resolved incident",
+        "id": 1
+      }
+    }
+    ~~~
+
+

docs/api/making-requests.md

@@ -1,7 +1,39 @@
 # Making requests
 
-## Endpoint
+The Cachet API provides access to incidents and components, allowing you to view, create and update via JSON requests.
 
-## Authorization
+The API is accessible from `http://<cachet-url>/api/<endpoint>`
 
-## Security
+## Examples
+
+You can use curl to interact with the API. There is no authentication required for `GET` requests:
+
+`curl -XGET curl -XGET http://status.cachethq.io/api/components`
+
+In order to create incidents, you must send the a json string with the required payload and authenticate. More information can be found in the Endpoints documentation listed below.
+
+Here's a simple example:
+
+`curl -u username@example.com -H "Content-Type: application/json" -d '{"name":"API","description":"An example description","status":1}' http://status.cachethq.io/api/components`
+
+
+# Endpoints
+
+## `/components`
+List and create components
+
+See [Component API documentation](components.md) for more information
+
+## `/incidents`
+List and create and update incidents
+
+See [Incidents API documentation](incidents.md) for more information
+
+## `/metrics`
+List and add metrics
+
+See [Incidents API documentation](metrics.md) for more information
+
+# Authorization
+
+# Security

docs/api/metrics.md

@@ -0,0 +1,44 @@
+# API Metrics
+
+**_Work In Progress_**
+
+## `/metrics`
+
+Interact with metrics
+
+Example URL: `http://status.cachethq.io/api/metrics`
+
+* `GET`: returns a list of the current metrics
+  - success: 200:
+  
+    ~~~json
+    To be confirmed
+    ~~~
+
+* `POST`: Create an metric
+  - payload
+
+    ~~~json
+    To be confirmed
+    ~~~
+
+
+
+## `/metrics/:id`
+
+Show a single metric
+
+Example URL: `http://status.cachethq.io/api/metrics/1`
+
+* `GET`: Return a single metric
+  - success: 200:
+
+    ~~~json
+    To be confirmed
+    ~~~
+
+## `/metrics/points`
+
+To be confirmed
+
+

docs/api/readme.md

@@ -1 +1,12 @@
 # Cachet API
+
+## Making Requests
+
+Cachet's API is JSON based, making interaction simple. Take a look at the [Making Requests](making-requests.md) page for some simple examples
+
+## Endpoints
+
+There are endpoints for [Components](components.md), [Incidents](incidents.md) and [Metrics](metrics.md) with more to come soon.
+
+
+