From 5bb8b7807472560912451fd9bb9bdf34076be19d Mon Sep 17 00:00:00 2001 From: lbriggs Date: Wed, 31 Dec 2014 15:58:37 +0000 Subject: [PATCH] Adding initial API docs --- INSTALL.md | 1 + docs/api/components.md | 78 +++++++++++++++++++++++++++++++++++++ docs/api/incidents.md | 76 ++++++++++++++++++++++++++++++++++++ docs/api/making-requests.md | 38 ++++++++++++++++-- docs/api/metrics.md | 44 +++++++++++++++++++++ docs/api/readme.md | 11 ++++++ 6 files changed, 245 insertions(+), 3 deletions(-) create mode 100644 docs/api/components.md create mode 100644 docs/api/incidents.md create mode 100644 docs/api/metrics.md diff --git a/INSTALL.md b/INSTALL.md index 1c39c84e..ec248af2 100644 --- a/INSTALL.md +++ b/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 diff --git a/docs/api/components.md b/docs/api/components.md new file mode 100644 index 00000000..e87ecfdf --- /dev/null +++ b/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 + } + ] + } + ~~~ + + diff --git a/docs/api/incidents.md b/docs/api/incidents.md new file mode 100644 index 00000000..9cab49a8 --- /dev/null +++ b/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 + } + } + ~~~ + + diff --git a/docs/api/making-requests.md b/docs/api/making-requests.md index facc4486..5a207372 100644 --- a/docs/api/making-requests.md +++ b/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:///api/` -## 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 diff --git a/docs/api/metrics.md b/docs/api/metrics.md new file mode 100644 index 00000000..61ce542c --- /dev/null +++ b/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 + + diff --git a/docs/api/readme.md b/docs/api/readme.md index 55a2a43d..8c6fca39 100644 --- a/docs/api/readme.md +++ b/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. + + +