From 81be4e261242a24b50d32c42f415c23c52404381 Mon Sep 17 00:00:00 2001 From: Patrick O'Carroll Date: Thu, 5 Oct 2017 19:01:03 +0200 Subject: [PATCH] Update codebox (#9430) * updated the codeboxes in docs * codebox change from json to http --- docs/sources/administration/cli.md | 2 +- .../features/datasources/cloudwatch.md | 19 +- .../features/datasources/elasticsearch.md | 6 +- docs/sources/http_api/admin.md | 438 ++++++++++-------- docs/sources/http_api/alerting.md | 282 +++++------ docs/sources/http_api/auth.md | 95 ++-- docs/sources/http_api/dashboard.md | 158 ++++--- docs/sources/http_api/data_source.md | 329 +++++++------ docs/sources/http_api/org.md | 424 +++++++++-------- docs/sources/http_api/other.md | 86 ++-- docs/sources/http_api/preferences.md | 92 ++-- docs/sources/http_api/snapshot.md | 114 +++-- docs/sources/http_api/user.md | 399 +++++++++------- docs/sources/installation/behind_proxy.md | 10 +- docs/sources/installation/configuration.md | 181 +++++--- docs/sources/installation/debian.md | 8 +- docs/sources/installation/docker.md | 14 +- docs/sources/installation/ldap.md | 4 +- docs/sources/installation/mac.md | 12 +- docs/sources/installation/rpm.md | 67 ++- docs/sources/installation/upgrading.md | 10 +- .../plugins/developing/code-styleguide.md | 4 +- .../sources/plugins/developing/datasources.md | 2 +- docs/sources/plugins/installation.md | 20 +- docs/sources/project/building_from_source.md | 16 +- docs/sources/reference/dashboard.md | 2 +- docs/sources/reference/sharing.md | 2 +- docs/sources/tutorials/api_org_token_howto.md | 12 +- docs/sources/tutorials/hubot_howto.md | 26 +- 29 files changed, 1574 insertions(+), 1260 deletions(-) diff --git a/docs/sources/administration/cli.md b/docs/sources/administration/cli.md index 645f75ab412..2be1881cfab 100644 --- a/docs/sources/administration/cli.md +++ b/docs/sources/administration/cli.md @@ -41,7 +41,7 @@ then there are two flags that can be used to set homepath and the config file pa If you have not lost the admin password then it is better to set in the Grafana UI. If you need to set the password in a script then the [Grafana API](http://docs.grafana.org/http_api/user/#change-password) can be used. Here is an example with curl using basic auth: -``` +```bash curl -X PUT -H "Content-Type: application/json" -d '{ "oldPassword": "admin", "newPassword": "newpass", diff --git a/docs/sources/features/datasources/cloudwatch.md b/docs/sources/features/datasources/cloudwatch.md index 61dd90d2881..29da06bfb1e 100644 --- a/docs/sources/features/datasources/cloudwatch.md +++ b/docs/sources/features/datasources/cloudwatch.md @@ -50,11 +50,12 @@ Create a file at `~/.aws/credentials`. That is the `HOME` path for user running Example content: - [default] - aws_access_key_id = asdsadasdasdasd - aws_secret_access_key = dasdasdsadasdasdasdsa - region = us-west-2 - +```bash +[default] +aws_access_key_id = asdsadasdasdasd +aws_secret_access_key = dasdasdsadasdasdasdsa +region = us-west-2 +``` ## Metric Query Editor @@ -117,7 +118,9 @@ Filters syntax: Example `ec2_instance_attribute()` query - ec2_instance_attribute(us-east-1, InstanceId, { "tag:Environment": [ "production" ] }) +```javascript +ec2_instance_attribute(us-east-1, InstanceId, { "tag:Environment": [ "production" ] }) +``` ### Selecting Attributes @@ -156,7 +159,9 @@ Tags can be selected by prepending the tag name with `Tags.` Example `ec2_instance_attribute()` query - ec2_instance_attribute(us-east-1, Tags.Name, { "tag:Team": [ "sysops" ] }) +```javascript +ec2_instance_attribute(us-east-1, Tags.Name, { "tag:Team": [ "sysops" ] }) +``` ## Cost diff --git a/docs/sources/features/datasources/elasticsearch.md b/docs/sources/features/datasources/elasticsearch.md index 25cdb98c8c5..be4e3e78e49 100644 --- a/docs/sources/features/datasources/elasticsearch.md +++ b/docs/sources/features/datasources/elasticsearch.md @@ -38,8 +38,10 @@ Proxy access means that the Grafana backend will proxy all requests from the bro If you select direct access you must update your Elasticsearch configuration to allow other domains to access Elasticsearch from the browser. You do this by specifying these to options in your **elasticsearch.yml** config file. - http.cors.enabled: true - http.cors.allow-origin: "*" +```bash +http.cors.enabled: true +http.cors.allow-origin: "*" +``` ### Index settings diff --git a/docs/sources/http_api/admin.md b/docs/sources/http_api/admin.md index 55bec79c7f8..3ef5fb1136a 100644 --- a/docs/sources/http_api/admin.md +++ b/docs/sources/http_api/admin.md @@ -23,158 +23,162 @@ Only works with Basic Authentication (username and password). See [introduction] **Example Request**: - GET /api/admin/settings - Accept: application/json - Content-Type: application/json +```bash +GET /api/admin/settings +Accept: application/json +Content-Type: application/json +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - - { - "DEFAULT": - { - "app_mode":"production"}, - "analytics": - { - "google_analytics_ua_id":"", - "reporting_enabled":"false" - }, - "auth.anonymous":{ - "enabled":"true", - "org_name":"Main Org.", - "org_role":"Viewer" - }, - "auth.basic":{ - "enabled":"false" - }, - "auth.github":{ - "allow_sign_up":"false", - "allowed_domains":"", - "allowed_organizations":"", - "api_url":"https://api.github.com/user", - "auth_url":"https://github.com/login/oauth/authorize", - "client_id":"some_id", - "client_secret":"************", - "enabled":"false", - "scopes":"user:email", - "team_ids":"", - "token_url":"https://github.com/login/oauth/access_token" - }, - "auth.google":{ - "allow_sign_up":"false","allowed_domains":"", - "api_url":"https://www.googleapis.com/oauth2/v1/userinfo", - "auth_url":"https://accounts.google.com/o/oauth2/auth", - "client_id":"some_client_id", - "client_secret":"************", - "enabled":"false", - "scopes":"https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email", - "token_url":"https://accounts.google.com/o/oauth2/token" - }, - "auth.ldap":{ - "config_file":"/etc/grafana/ldap.toml", - "enabled":"false" - }, - "auth.proxy":{ - "auto_sign_up":"true", - "enabled":"false", - "header_name":"X-WEBAUTH-USER", - "header_property":"username" - }, - "dashboards.json":{ - "enabled":"false", - "path":"/var/lib/grafana/dashboards" - }, - "database":{ - "host":"127.0.0.1:0000", - "name":"grafana", - "password":"************", - "path":"grafana.db", - "ssl_mode":"disable", - "type":"sqlite3", - "user":"root" - }, - "emails":{ - "templates_pattern":"emails/*.html", - "welcome_email_on_sign_up":"false" - }, - "event_publisher":{ - "enabled":"false", - "exchange":"grafana_events", - "rabbitmq_url":"amqp://localhost/" - }, - "log":{ - "buffer_len":"10000", - "level":"Info", - "mode":"file" - }, - "log.console":{ - "level":"" - }, - "log.file":{ - "daily_rotate":"true", - "file_name":"", - "level":"", - "log_rotate":"true", - "max_days":"7", - "max_lines":"1000000", - "max_lines_shift":"28", - "max_size_shift":"" - }, - "paths":{ - "data":"/tsdb/grafana", - "logs":"/logs/apps/grafana"}, - "security":{ - "admin_password":"************", - "admin_user":"admin", - "cookie_remember_name":"grafana_remember", - "cookie_username":"grafana_user", - "disable_gravatar":"false", - "login_remember_days":"7", - "secret_key":"************" - }, - "server":{ - "cert_file":"", - "cert_key":"", - "domain":"mygraf.com", - "enable_gzip":"false", - "enforce_domain":"false", - "http_addr":"127.0.0.1", - "http_port":"0000", - "protocol":"http", - "root_url":"%(protocol)s://%(domain)s:%(http_port)s/", - "router_logging":"true", - "data_proxy_logging":"true", - "static_root_path":"public" - }, - "session":{ - "cookie_name":"grafana_sess", - "cookie_secure":"false", - "gc_interval_time":"", - "provider":"file", - "provider_config":"sessions", - "session_life_time":"86400" - }, - "smtp":{ - "cert_file":"", - "enabled":"false", - "from_address":"admin@grafana.localhost", - "from_name":"Grafana", - "ehlo_identity":"dashboard.example.com", - "host":"localhost:25", - "key_file":"", - "password":"************", - "skip_verify":"false", - "user":""}, - "users":{ - "allow_org_create":"true", - "allow_sign_up":"false", - "auto_assign_org":"true", - "auto_assign_org_role":"Viewer" - } - } +```bash +HTTP/1.1 200 +Content-Type: application/json +{ +"DEFAULT": +{ + "app_mode":"production"}, + "analytics": + { + "google_analytics_ua_id":"", + "reporting_enabled":"false" + }, + "auth.anonymous":{ + "enabled":"true", + "org_name":"Main Org.", + "org_role":"Viewer" + }, + "auth.basic":{ + "enabled":"false" + }, + "auth.github":{ + "allow_sign_up":"false", + "allowed_domains":"", + "allowed_organizations":"", + "api_url":"https://api.github.com/user", + "auth_url":"https://github.com/login/oauth/authorize", + "client_id":"some_id", + "client_secret":"************", + "enabled":"false", + "scopes":"user:email", + "team_ids":"", + "token_url":"https://github.com/login/oauth/access_token" + }, + "auth.google":{ + "allow_sign_up":"false","allowed_domains":"", + "api_url":"https://www.googleapis.com/oauth2/v1/userinfo", + "auth_url":"https://accounts.google.com/o/oauth2/auth", + "client_id":"some_client_id", + "client_secret":"************", + "enabled":"false", + "scopes":"https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email", + "token_url":"https://accounts.google.com/o/oauth2/token" + }, + "auth.ldap":{ + "config_file":"/etc/grafana/ldap.toml", + "enabled":"false" + }, + "auth.proxy":{ + "auto_sign_up":"true", + "enabled":"false", + "header_name":"X-WEBAUTH-USER", + "header_property":"username" + }, + "dashboards.json":{ + "enabled":"false", + "path":"/var/lib/grafana/dashboards" + }, + "database":{ + "host":"127.0.0.1:0000", + "name":"grafana", + "password":"************", + "path":"grafana.db", + "ssl_mode":"disable", + "type":"sqlite3", + "user":"root" + }, + "emails":{ + "templates_pattern":"emails/*.html", + "welcome_email_on_sign_up":"false" + }, + "event_publisher":{ + "enabled":"false", + "exchange":"grafana_events", + "rabbitmq_url":"amqp://localhost/" + }, + "log":{ + "buffer_len":"10000", + "level":"Info", + "mode":"file" + }, + "log.console":{ + "level":"" + }, + "log.file":{ + "daily_rotate":"true", + "file_name":"", + "level":"", + "log_rotate":"true", + "max_days":"7", + "max_lines":"1000000", + "max_lines_shift":"28", + "max_size_shift":"" + }, + "paths":{ + "data":"/tsdb/grafana", + "logs":"/logs/apps/grafana"}, + "security":{ + "admin_password":"************", + "admin_user":"admin", + "cookie_remember_name":"grafana_remember", + "cookie_username":"grafana_user", + "disable_gravatar":"false", + "login_remember_days":"7", + "secret_key":"************" + }, + "server":{ + "cert_file":"", + "cert_key":"", + "domain":"mygraf.com", + "enable_gzip":"false", + "enforce_domain":"false", + "http_addr":"127.0.0.1", + "http_port":"0000", + "protocol":"http", + "root_url":"%(protocol)s://%(domain)s:%(http_port)s/", + "router_logging":"true", + "data_proxy_logging":"true", + "static_root_path":"public" + }, + "session":{ + "cookie_name":"grafana_sess", + "cookie_secure":"false", + "gc_interval_time":"", + "provider":"file", + "provider_config":"sessions", + "session_life_time":"86400" + }, + "smtp":{ + "cert_file":"", + "enabled":"false", + "from_address":"admin@grafana.localhost", + "from_name":"Grafana", + "ehlo_identity":"dashboard.example.com", + "host":"localhost:25", + "key_file":"", + "password":"************", + "skip_verify":"false", + "user":"" + }, + "users":{ + "allow_org_create":"true", + "allow_sign_up":"false", + "auto_assign_org":"true", + "auto_assign_org_role":"Viewer" + } +} +``` ## Grafana Stats `GET /api/admin/stats` @@ -183,26 +187,30 @@ Only works with Basic Authentication (username and password). See [introduction] **Example Request**: - GET /api/admin/stats - Accept: application/json - Content-Type: application/json +```bash +GET /api/admin/stats +Accept: application/json +Content-Type: application/json +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```json +HTTP/1.1 200 +Content-Type: application/json - { - "user_count":2, - "org_count":1, - "dashboard_count":4, - "db_snapshot_count":2, - "db_tag_count":6, - "data_source_count":1, - "playlist_count":1, - "starred_db_count":2, - "grafana_admin_count":2 - } +{ + "user_count":2, + "org_count":1, + "dashboard_count":4, + "db_snapshot_count":2, + "db_tag_count":6, + "data_source_count":1, + "playlist_count":1, + "starred_db_count":2, + "grafana_admin_count":2 +} +``` ## Global Users @@ -211,24 +219,28 @@ Only works with Basic Authentication (username and password). See [introduction] Create new user. Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation. **Example Request**: +```json - POST /api/admin/users HTTP/1.1 - Accept: application/json - Content-Type: application/json +POST /api/admin/users HTTP/1.1 +Accept: application/json +Content-Type: application/json - { - "name":"User", - "email":"user@graf.com", - "login":"user", - "password":"userpassword" - } +{ + "name":"User", + "email":"user@graf.com", + "login":"user", + "password":"userpassword" +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```json +HTTP/1.1 200 +Content-Type: application/json - {"id":5,"message":"User created"} +{"id":5,"message":"User created"} +``` ## Password for User @@ -239,18 +251,22 @@ Change password for a specific user. **Example Request**: - PUT /api/admin/users/2/password HTTP/1.1 - Accept: application/json - Content-Type: application/json +```json +PUT /api/admin/users/2/password HTTP/1.1 +Accept: application/json +Content-Type: application/json - {"password":"userpassword"} +{"password":"userpassword"} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```json +HTTP/1.1 200 +Content-Type: application/json - {"message": "User password updated"} +{"message": "User password updated"} +``` ## Permissions @@ -260,18 +276,22 @@ Only works with Basic Authentication (username and password). See [introduction] **Example Request**: - PUT /api/admin/users/2/permissions HTTP/1.1 - Accept: application/json - Content-Type: application/json +```json +PUT /api/admin/users/2/permissions HTTP/1.1 +Accept: application/json +Content-Type: application/json - {"isGrafanaAdmin": true} +{"isGrafanaAdmin": true} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```json +HTTP/1.1 200 +Content-Type: application/json - {message: "User permissions updated"} +{message: "User permissions updated"} +``` ## Delete global User @@ -281,16 +301,20 @@ Only works with Basic Authentication (username and password). See [introduction] **Example Request**: - DELETE /api/admin/users/2 HTTP/1.1 - Accept: application/json - Content-Type: application/json +```json +DELETE /api/admin/users/2 HTTP/1.1 +Accept: application/json +Content-Type: application/json +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```json +HTTP/1.1 200 +Content-Type: application/json - {message: "User deleted"} +{message: "User deleted"} +``` ## Pause all alerts @@ -300,13 +324,15 @@ Only works with Basic Authentication (username and password). See [introduction] **Example Request**: - POST /api/admin/pause-all-alerts HTTP/1.1 - Accept: application/json - Content-Type: application/json +```json +POST /api/admin/pause-all-alerts HTTP/1.1 +Accept: application/json +Content-Type: application/json - { - "paused": true - } +{ + "paused": true +} +``` JSON Body schema: @@ -314,7 +340,9 @@ JSON Body schema: **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```json +HTTP/1.1 200 +Content-Type: application/json - {state: "new state", message: "alerts pause/un paused", "alertsAffected": 100} +{state: "new state", message: "alerts pause/un paused", "alertsAffected": 100} +``` \ No newline at end of file diff --git a/docs/sources/http_api/alerting.md b/docs/sources/http_api/alerting.md index 1aab7253373..c5172c64203 100644 --- a/docs/sources/http_api/alerting.md +++ b/docs/sources/http_api/alerting.md @@ -23,11 +23,12 @@ This API can also be used to create, update and delete alert notifications. **Example Request**: - GET /api/alerts HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - +```http +GET /api/alerts HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` Querystring Parameters: These parameters are used as querystring parameters. For example: @@ -41,28 +42,30 @@ This API can also be used to create, update and delete alert notifications. **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - [ +```http +HTTP/1.1 200 +Content-Type: application/json +[ + { + "id": 1, + "dashboardId": 1, + "panelId": 1, + "name": "fire place sensor", + "message": "Someone is trying to break in through the fire place", + "state": "alerting", + "evalDate": "0001-01-01T00:00:00Z", + "evalData": [ { - "id": 1, - "dashboardId": 1, - "panelId": 1, - "name": "fire place sensor", - "message": "Someone is trying to break in through the fire place", - "state": "alerting", - "evalDate": "0001-01-01T00:00:00Z", - "evalData": [ - { - "metric": "fire", - "tags": null, - "value": 5.349999999999999 - } - "newStateDate": "2016-12-25", - "executionError": "", - "dashboardUri": "http://grafana.com/dashboard/db/sensors" + "metric": "fire", + "tags": null, + "value": 5.349999999999999 } - ] + "newStateDate": "2016-12-25", + "executionError": "", + "dashboardUri": "http://grafana.com/dashboard/db/sensors" + } +] +``` ## Get one alert @@ -70,26 +73,30 @@ This API can also be used to create, update and delete alert notifications. **Example Request**: - GET /api/alerts/1 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/alerts/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - { - "id": 1, - "dashboardId": 1, - "panelId": 1, - "name": "fire place sensor", - "message": "Someone is trying to break in through the fire place", - "state": "alerting", - "newStateDate": "2016-12-25", - "executionError": "", - "dashboardUri": "http://grafana.com/dashboard/db/sensors" - } +```http +HTTP/1.1 200 +Content-Type: application/json +{ + "id": 1, + "dashboardId": 1, + "panelId": 1, + "name": "fire place sensor", + "message": "Someone is trying to break in through the fire place", + "state": "alerting", + "newStateDate": "2016-12-25", + "executionError": "", + "dashboardUri": "http://grafana.com/dashboard/db/sensors" +} +``` ## Pause alert @@ -97,14 +104,16 @@ This API can also be used to create, update and delete alert notifications. **Example Request**: - POST /api/alerts/1/pause HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +POST /api/alerts/1/pause HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - { - "paused": true - } +{ + "paused": true +} +``` The :id query parameter is the id of the alert to be paused or unpaused. @@ -114,13 +123,15 @@ JSON Body Schema: **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - { - "alertId": 1, - "state": "Paused", - "message": "alert paused" - } +```http +HTTP/1.1 200 +Content-Type: application/json +{ + "alertId": 1, + "state": "Paused", + "message": "alert paused" +} +``` ## Get alert notifications @@ -128,26 +139,29 @@ JSON Body Schema: **Example Request**: - GET /api/alert-notifications HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - +```http +GET /api/alert-notifications HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - { - "id": 1, - "name": "Team A", - "type": "email", - "isDefault": true, - "created": "2017-01-01 12:45", - "updated": "2017-01-01 12:45" - } +{ + "id": 1, + "name": "Team A", + "type": "email", + "isDefault": true, + "created": "2017-01-01 12:45", + "updated": "2017-01-01 12:45" +} +``` ## Create alert notification @@ -155,34 +169,37 @@ JSON Body Schema: **Example Request**: - POST /api/alert-notifications HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "name": "new alert notification", //Required - "type": "email", //Required - "isDefault": false, - "settings": { - "addresses": "carl@grafana.com;dev@grafana.com" - } - } +```http +POST /api/alert-notifications HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +{ + "name": "new alert notification", //Required + "type": "email", //Required + "isDefault": false, + "settings": { + "addresses": "carl@grafana.com;dev@grafana.com" + } +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - { - "id": 1, - "name": "new alert notification", - "type": "email", - "isDefault": false, - "settings": { addresses: "carl@grafana.com;dev@grafana.com"} } - "created": "2017-01-01 12:34", - "updated": "2017-01-01 12:34" - } +```http +HTTP/1.1 200 +Content-Type: application/json +{ + "id": 1, + "name": "new alert notification", + "type": "email", + "isDefault": false, + "settings": { addresses: "carl@grafana.com;dev@grafana.com"} } + "created": "2017-01-01 12:34", + "updated": "2017-01-01 12:34" +} +``` ## Update alert notification @@ -190,35 +207,38 @@ JSON Body Schema: **Example Request**: - PUT /api/alert-notifications/1 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "id": 1, - "name": "new alert notification", //Required - "type": "email", //Required - "isDefault": false, - "settings": { - "addresses: "carl@grafana.com;dev@grafana.com" - } - } +```http +PUT /api/alert-notifications/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +{ + "id": 1, + "name": "new alert notification", //Required + "type": "email", //Required + "isDefault": false, + "settings": { + "addresses: "carl@grafana.com;dev@grafana.com" + } +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - { - "id": 1, - "name": "new alert notification", - "type": "email", - "isDefault": false, - "settings": { addresses: "carl@grafana.com;dev@grafana.com"} } - "created": "2017-01-01 12:34", - "updated": "2017-01-01 12:34" - } +```http +HTTP/1.1 200 +Content-Type: application/json +{ + "id": 1, + "name": "new alert notification", + "type": "email", + "isDefault": false, + "settings": { addresses: "carl@grafana.com;dev@grafana.com"} } + "created": "2017-01-01 12:34", + "updated": "2017-01-01 12:34" +} +``` ## Delete alert notification @@ -226,15 +246,19 @@ JSON Body Schema: **Example Request**: - DELETE /api/alert-notifications/1 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +DELETE /api/alert-notifications/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - { - "message": "Notification deleted" - } +```http +HTTP/1.1 200 +Content-Type: application/json +{ + "message": "Notification deleted" +} +``` \ No newline at end of file diff --git a/docs/sources/http_api/auth.md b/docs/sources/http_api/auth.md index d8ded124ac5..b526031fdeb 100644 --- a/docs/sources/http_api/auth.md +++ b/docs/sources/http_api/auth.md @@ -21,7 +21,7 @@ If basic auth is enabled (it is enabled by default) you can authenticate your HT standard basic auth. Basic auth will also authenticate LDAP users. curl example: -``` +```bash ?curl http://admin:admin@localhost:3000/api/org {"id":1,"name":"Main Org."} ``` @@ -36,9 +36,11 @@ You use the token in all requests in the `Authorization` header, like this: **Example**: - GET http://your.grafana.com/api/dashboards/db/mydash HTTP/1.1 - Accept: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET http://your.grafana.com/api/dashboards/db/mydash HTTP/1.1 +Accept: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` The `Authorization` header value should be `Bearer `. @@ -50,28 +52,32 @@ The `Authorization` header value should be `Bearer `. **Example Request**: - GET /api/auth/keys HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/auth/keys HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - [ - { - "id": 3, - "name": "API", - "role": "Admin" - }, - { - "id": 1, - "name": "TestAdmin", - "role": "Admin" - } - ] +[ + { + "id": 3, + "name": "API", + "role": "Admin" + }, + { + "id": 1, + "name": "TestAdmin", + "role": "Admin" + } +] +``` ## Create API Key @@ -79,15 +85,17 @@ The `Authorization` header value should be `Bearer `. **Example Request**: - POST /api/auth/keys HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +POST /api/auth/keys HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - { - "name": "mykey", - "role": "Admin" - } +{ + "name": "mykey", + "role": "Admin" +} +``` JSON Body schema: @@ -96,10 +104,12 @@ JSON Body schema: **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"name":"mykey","key":"eyJrIjoiWHZiSWd3NzdCYUZnNUtibE9obUpESmE3bzJYNDRIc0UiLCJuIjoibXlrZXkiLCJpZCI6MX1="} +{"name":"mykey","key":"eyJrIjoiWHZiSWd3NzdCYUZnNUtibE9obUpESmE3bzJYNDRIc0UiLCJuIjoibXlrZXkiLCJpZCI6MX1="} +``` ## Delete API Key @@ -107,14 +117,17 @@ JSON Body schema: **Example Request**: - DELETE /api/auth/keys/3 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - +```http +DELETE /api/auth/keys/3 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"API key deleted"} +{"message":"API key deleted"} +``` \ No newline at end of file diff --git a/docs/sources/http_api/dashboard.md b/docs/sources/http_api/dashboard.md index 899c76ce6e0..300e5613db4 100644 --- a/docs/sources/http_api/dashboard.md +++ b/docs/sources/http_api/dashboard.md @@ -158,53 +158,57 @@ Will return the home dashboard. **Example Request**: - GET /api/dashboards/home HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/dashboards/home HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json +{ + "meta": { + "isHome":true, + "canSave":false, + "canEdit":false, + "canStar":false, + "slug":"", + "expires":"0001-01-01T00:00:00Z", + "created":"0001-01-01T00:00:00Z" + }, + "dashboard": { + "editable":false, + "hideControls":true, + "nav":[ { - "meta": { - "isHome":true, - "canSave":false, - "canEdit":false, - "canStar":false, - "slug":"", - "expires":"0001-01-01T00:00:00Z", - "created":"0001-01-01T00:00:00Z" - }, - "dashboard": { - "editable":false, - "hideControls":true, - "nav":[ - { - "enable":false, - "type":"timepicker" - } - ], - "rows": [ - { - - } - ], - "style":"dark", - "tags":[], - "templating":{ - "list":[ - ] - }, - "time":{ - }, - "timezone":"browser", - "title":"Home", - "version":5 - } + "enable":false, + "type":"timepicker" } + ], + "rows": [ + { + + } + ], + "style":"dark", + "tags":[], + "templating":{ + "list":[ + ] + }, + "time":{ + }, + "timezone":"browser", + "title":"Home", + "version":5 + } +} +``` ## Tags for Dashboard @@ -215,26 +219,30 @@ Get all tags of dashboards **Example Request**: - GET /api/dashboards/tags HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/dashboards/tags HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - [ - { - "term":"tag1", - "count":1 - }, - { - "term":"tag2", - "count":4 - } - ] +[ + { + "term":"tag1", + "count":1 + }, + { + "term":"tag2", + "count":4 + } +] +``` ## Search Dashboards @@ -249,23 +257,27 @@ Query parameters: **Example Request**: - GET /api/search?query=MyDashboard&starred=true&tag=prod HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/search?query=MyDashboard&starred=true&tag=prod HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - [ - { - "id":1, - "title":"Production Overview", - "uri":"db/production-overview", - "type":"dash-db", - "tags":[], - "isStarred":false - } - ] +[ + { + "id":1, + "title":"Production Overview", + "uri":"db/production-overview", + "type":"dash-db", + "tags":[], + "isStarred":false + } +] +``` \ No newline at end of file diff --git a/docs/sources/http_api/data_source.md b/docs/sources/http_api/data_source.md index 62b09fb5d2c..364b55b0cfc 100644 --- a/docs/sources/http_api/data_source.md +++ b/docs/sources/http_api/data_source.md @@ -18,34 +18,38 @@ parent = "http_api" **Example Request**: - GET /api/datasources HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/datasources HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - [ - { - "id":1, - "orgId":1, - "name":"datasource_elastic", - "type":"elasticsearch", - "access":"proxy", - "url":"http://mydatasource.com", - "password":"", - "user":"", - "database":"grafana-dash", - "basicAuth":false, - "basicAuthUser":"", - "basicAuthPassword":"", - "isDefault":false, - "jsonData":null - } - ] +[ + { + "id":1, + "orgId":1, + "name":"datasource_elastic", + "type":"elasticsearch", + "access":"proxy", + "url":"http://mydatasource.com", + "password":"", + "user":"", + "database":"grafana-dash", + "basicAuth":false, + "basicAuthUser":"", + "basicAuthPassword":"", + "isDefault":false, + "jsonData":null + } +] +``` ## Get a single data sources by Id @@ -53,32 +57,36 @@ parent = "http_api" **Example Request**: - GET /api/datasources/1 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/datasources/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - { - "id":1, - "orgId":1, - "name":"test_datasource", - "type":"graphite", - "access":"proxy", - "url":"http://mydatasource.com", - "password":"", - "user":"", - "database":"", - "basicAuth":false, - "basicAuthUser":"", - "basicAuthPassword":"", - "isDefault":false, - "jsonData":null - } +{ + "id":1, + "orgId":1, + "name":"test_datasource", + "type":"graphite", + "access":"proxy", + "url":"http://mydatasource.com", + "password":"", + "user":"", + "database":"", + "basicAuth":false, + "basicAuthUser":"", + "basicAuthPassword":"", + "isDefault":false, + "jsonData":null +} +``` ## Get a single data source by Name @@ -86,32 +94,36 @@ parent = "http_api" **Example Request**: - GET /api/datasources/name/test_datasource HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/datasources/name/test_datasource HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - { - "id":1, - "orgId":1, - "name":"test_datasource", - "type":"graphite", - "access":"proxy", - "url":"http://mydatasource.com", - "password":"", - "user":"", - "database":"", - "basicAuth":false, - "basicAuthUser":"", - "basicAuthPassword":"", - "isDefault":false, - "jsonData":null - } +{ + "id":1, + "orgId":1, + "name":"test_datasource", + "type":"graphite", + "access":"proxy", + "url":"http://mydatasource.com", + "password":"", + "user":"", + "database":"", + "basicAuth":false, + "basicAuthUser":"", + "basicAuthPassword":"", + "isDefault":false, + "jsonData":null +} +``` ## Get data source Id by Name @@ -119,19 +131,23 @@ parent = "http_api" **Example Request**: - GET /api/datasources/id/test_datasource HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/datasources/id/test_datasource HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - { - "id":1 - } +{ + "id":1 +} +``` ## Create data source @@ -139,48 +155,53 @@ parent = "http_api" **Example Graphite Request**: - POST /api/datasources HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +POST /api/datasources HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - { - "name":"test_datasource", - "type":"graphite", - "url":"http://mydatasource.com", - "access":"proxy", - "basicAuth":false - } +{ + "name":"test_datasource", + "type":"graphite", + "url":"http://mydatasource.com", + "access":"proxy", + "basicAuth":false +} +``` **Example CloudWatch Request**: - ``` - POST /api/datasources HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "name": "test_datasource", - "type": "cloudwatch", - "url": "http://monitoring.us-west-1.amazonaws.com", - "access": "proxy", - "jsonData": { - "authType": "keys", - "defaultRegion": "us-west-1" - }, - "secureJsonData": { - "accessKey": "Ol4pIDpeKSA6XikgOl4p", - "secretKey": "dGVzdCBrZXkgYmxlYXNlIGRvbid0IHN0ZWFs" - } + +```http +POST /api/datasources HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +{ + "name": "test_datasource", + "type": "cloudwatch", + "url": "http://monitoring.us-west-1.amazonaws.com", + "access": "proxy", + "jsonData": { + "authType": "keys", + "defaultRegion": "us-west-1" + }, + "secureJsonData": { + "accessKey": "Ol4pIDpeKSA6XikgOl4p", + "secretKey": "dGVzdCBrZXkgYmxlYXNlIGRvbid0IHN0ZWFs" } - ``` +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"id":1,"message":"Datasource added", "name": "test_datasource"} +{"id":1,"message":"Datasource added", "name": "test_datasource"} +``` ## Update an existing data source @@ -188,34 +209,38 @@ parent = "http_api" **Example Request**: - PUT /api/datasources/1 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +PUT /api/datasources/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - { - "id":1, - "orgId":1, - "name":"test_datasource", - "type":"graphite", - "access":"proxy", - "url":"http://mydatasource.com", - "password":"", - "user":"", - "database":"", - "basicAuth":true, - "basicAuthUser":"basicuser", - "basicAuthPassword":"basicuser", - "isDefault":false, - "jsonData":null - } +{ + "id":1, + "orgId":1, + "name":"test_datasource", + "type":"graphite", + "access":"proxy", + "url":"http://mydatasource.com", + "password":"", + "user":"", + "database":"", + "basicAuth":true, + "basicAuthUser":"basicuser", + "basicAuthPassword":"basicuser", + "isDefault":false, + "jsonData":null +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"Datasource updated", "id": 1, "name": "test_datasource"} +{"message":"Datasource updated", "id": 1, "name": "test_datasource"} +``` ## Delete an existing data source by id @@ -223,17 +248,21 @@ parent = "http_api" **Example Request**: - DELETE /api/datasources/1 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +DELETE /api/datasources/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"Data source deleted"} +{"message":"Data source deleted"} +``` ## Delete an existing data source by name @@ -241,17 +270,21 @@ parent = "http_api" **Example Request**: - DELETE /api/datasources/name/test_datasource HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +DELETE /api/datasources/name/test_datasource HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"Data source deleted"} +{"message":"Data source deleted"} +``` ## Data source proxy calls diff --git a/docs/sources/http_api/org.md b/docs/sources/http_api/org.md index 72c995adedf..6542f00fd81 100644 --- a/docs/sources/http_api/org.md +++ b/docs/sources/http_api/org.md @@ -18,20 +18,24 @@ parent = "http_api" **Example Request**: - GET /api/org HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/org HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - { - "id":1, - "name":"Main Org." - } +{ + "id":1, + "name":"Main Org." +} +``` ## Get Organisation by Id @@ -39,57 +43,64 @@ parent = "http_api" **Example Request**: - GET /api/orgs/1 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/orgs/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - - { - "id":1, - "name":"Main Org.", - "address":{ - "address1":"", - "address2":"", - "city":"", - "zipCode":"", - "state":"", - "country":"" - } - } +```http +HTTP/1.1 200 +Content-Type: application/json +{ + "id":1, + "name":"Main Org.", + "address":{ + "address1":"", + "address2":"", + "city":"", + "zipCode":"", + "state":"", + "country":"" + } +} +``` ## Get Organisation by Name `GET /api/orgs/name/:orgName` **Example Request**: - GET /api/orgs/name/Main%20Org%2E HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/orgs/name/Main%20Org%2E HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - { - "id":1, - "name":"Main Org.", - "address":{ - "address1":"", - "address2":"", - "city":"", - "zipCode":"", - "state":"", - "country":"" - } - } +{ + "id":1, + "name":"Main Org.", + "address":{ + "address1":"", + "address2":"", + "city":"", + "zipCode":"", + "state":"", + "country":"" + } +} +``` ## Create Organisation @@ -97,26 +108,28 @@ parent = "http_api" **Example Request**: - POST /api/orgs HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "name":"New Org." - } +```http +POST /api/orgs HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +{ + "name":"New Org." +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - - { - "orgId":"1", - "message":"Organization created" - } +```http +HTTP/1.1 200 +Content-Type: application/json +{ + "orgId":"1", + "message":"Organization created" +} +``` ## Update current Organisation @@ -125,23 +138,25 @@ parent = "http_api" **Example Request**: - PUT /api/org HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "name":"Main Org." - } +```http +PUT /api/org HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +{ + "name":"Main Org." +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - - {"message":"Organization updated"} +```http +HTTP/1.1 200 +Content-Type: application/json +{"message":"Organization updated"} +``` ## Get all users within the actual organisation @@ -149,25 +164,29 @@ parent = "http_api" **Example Request**: - GET /api/org/users HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/org/users HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - [ - { - "orgId":1, - "userId":1, - "email":"admin@mygraf.com", - "login":"admin", - "role":"Admin" - } - ] +[ + { + "orgId":1, + "userId":1, + "email":"admin@mygraf.com", + "login":"admin", + "role":"Admin" + } +] +``` ## Add a new user to the actual organisation @@ -177,23 +196,26 @@ Adds a global user to the actual organisation. **Example Request**: - POST /api/org/users HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "role": "Admin", - "loginOrEmail": "admin" - } +```http +POST /api/org/users HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +{ + "role": "Admin", + "loginOrEmail": "admin" +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"User added to organization"} +{"message":"User added to organization"} +``` ## Updates the given user @@ -201,23 +223,25 @@ Adds a global user to the actual organisation. **Example Request**: - PATCH /api/org/users/1 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "role": "Viewer", - } +```http +PATCH /api/org/users/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +{ + "role": "Viewer", +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - - {"message":"Organization user updated"} +```http +HTTP/1.1 200 +Content-Type: application/json +{"message":"Organization user updated"} +``` ## Delete user in actual organisation @@ -225,18 +249,21 @@ Adds a global user to the actual organisation. **Example Request**: - DELETE /api/org/users/1 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +DELETE /api/org/users/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - - {"message":"User removed from organization"} +```http +HTTP/1.1 200 +Content-Type: application/json +{"message":"User removed from organization"} +``` # Organisations @@ -246,22 +273,26 @@ Adds a global user to the actual organisation. **Example Request**: - GET /api/orgs HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/orgs HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - [ - { - "id":1, - "name":"Main Org." - } - ] +[ + { + "id":1, + "name":"Main Org." + } +] +``` ## Update Organisation @@ -271,22 +302,25 @@ Update Organisation, fields *Adress 1*, *Adress 2*, *City* are not implemented y **Example Request**: - PUT /api/orgs/1 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "name":"Main Org 2." - } +```http +PUT /api/orgs/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +{ + "name":"Main Org 2." +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"Organization updated"} +{"message":"Organization updated"} +``` ## Get Users in Organisation @@ -294,24 +328,28 @@ Update Organisation, fields *Adress 1*, *Adress 2*, *City* are not implemented y **Example Request**: - GET /api/orgs/1/users HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/orgs/1/users HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - [ - { - "orgId":1, - "userId":1, - "email":"admin@mygraf.com", - "login":"admin", - "role":"Admin" - } - ] +```http +HTTP/1.1 200 +Content-Type: application/json +[ + { + "orgId":1, + "userId":1, + "email":"admin@mygraf.com", + "login":"admin", + "role":"Admin" + } +] +``` ## Add User in Organisation @@ -319,22 +357,26 @@ Update Organisation, fields *Adress 1*, *Adress 2*, *City* are not implemented y **Example Request**: - POST /api/orgs/1/users HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +POST /api/orgs/1/users HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - { - "loginOrEmail":"user", - "role":"Viewer" - } +{ + "loginOrEmail":"user", + "role":"Viewer" +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"User added to organization"} +{"message":"User added to organization"} +``` ## Update Users in Organisation @@ -342,21 +384,25 @@ Update Organisation, fields *Adress 1*, *Adress 2*, *City* are not implemented y **Example Request**: - PATCH /api/orgs/1/users/2 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +PATCH /api/orgs/1/users/2 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - { - "role":"Admin" - } +{ + "role":"Admin" +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"Organization user updated"} +{"message":"Organization user updated"} +``` ## Delete User in Organisation @@ -364,14 +410,18 @@ Update Organisation, fields *Adress 1*, *Adress 2*, *City* are not implemented y **Example Request**: - DELETE /api/orgs/1/users/2 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +DELETE /api/orgs/1/users/2 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"User removed from organization"} +{"message":"User removed from organization"} +``` \ No newline at end of file diff --git a/docs/sources/http_api/other.md b/docs/sources/http_api/other.md index 65d18f94ea4..5bf0cde05fe 100644 --- a/docs/sources/http_api/other.md +++ b/docs/sources/http_api/other.md @@ -18,43 +18,47 @@ parent = "http_api" **Example Request**: - GET /api/frontend/settings HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/frontend/settings HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - { - "allowOrgCreate":true, - "appSubUrl":"", - "buildInfo":{ - "buildstamp":xxxxxx, - "commit":"vyyyy", - "version":"zzzzz" - }, - "datasources":{ - "datasourcename":{ - "index":"grafana-dash", - "meta":{ - "annotations":true, - "module":"plugins/datasource/grafana/datasource", - "name":"Grafana", - "partials":{ - "annotations":"app/plugins/datasource/grafana/partials/annotations.editor.html", - "config":"app/plugins/datasource/grafana/partials/config.html" - }, - "pluginType":"datasource", - "serviceName":"Grafana", - "type":"grafanasearch" - } - } - }, - "defaultDatasource": "Grafana" +{ + "allowOrgCreate":true, + "appSubUrl":"", + "buildInfo":{ + "buildstamp":xxxxxx, + "commit":"vyyyy", + "version":"zzzzz" + }, + "datasources":{ + "datasourcename":{ + "index":"grafana-dash", + "meta":{ + "annotations":true, + "module":"plugins/datasource/grafana/datasource", + "name":"Grafana", + "partials":{ + "annotations":"app/plugins/datasource/grafana/partials/annotations.editor.html", + "config":"app/plugins/datasource/grafana/partials/config.html" + }, + "pluginType":"datasource", + "serviceName":"Grafana", + "type":"grafanasearch" + } } + }, + "defaultDatasource": "Grafana" +} +``` # Login API @@ -64,14 +68,18 @@ parent = "http_api" **Example Request**: - GET /api/login/ping HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/login/ping HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message": "Logged in"} +{"message": "Logged in"} +``` \ No newline at end of file diff --git a/docs/sources/http_api/preferences.md b/docs/sources/http_api/preferences.md index a4b953cdaed..ac1d1ee7a0d 100644 --- a/docs/sources/http_api/preferences.md +++ b/docs/sources/http_api/preferences.md @@ -26,17 +26,21 @@ system default value. **Example Request**: - GET /api/user/preferences HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/user/preferences HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"theme":"","homeDashboardId":0,"timezone":""} +{"theme":"","homeDashboardId":0,"timezone":""} +``` ## Update Current User Prefs @@ -44,23 +48,27 @@ system default value. **Example Request**: - PUT /api/user/preferences HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +PUT /api/user/preferences HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - { - "theme": "", - "homeDashboardId":0, - "timezone":"utc" - } +{ + "theme": "", + "homeDashboardId":0, + "timezone":"utc" +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: text/plain; charset=utf-8 +```http +HTTP/1.1 200 +Content-Type: text/plain; charset=utf-8 - {"message":"Preferences updated"} +{"message":"Preferences updated"} +``` ## Get Current Org Prefs @@ -68,17 +76,21 @@ system default value. **Example Request**: - GET /api/org/preferences HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/org/preferences HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"theme":"","homeDashboardId":0,"timezone":""} +{"theme":"","homeDashboardId":0,"timezone":""} +``` ## Update Current Org Prefs @@ -86,20 +98,24 @@ system default value. **Example Request**: - PUT /api/org/preferences HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +PUT /api/org/preferences HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - { - "theme": "", - "homeDashboardId":0, - "timezone":"utc" - } +{ + "theme": "", + "homeDashboardId":0, + "timezone":"utc" +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: text/plain; charset=utf-8 +```http +HTTP/1.1 200 +Content-Type: text/plain; charset=utf-8 - {"message":"Preferences updated"} +{"message":"Preferences updated"} +``` \ No newline at end of file diff --git a/docs/sources/http_api/snapshot.md b/docs/sources/http_api/snapshot.md index d466d01e051..5cecdb85fc3 100644 --- a/docs/sources/http_api/snapshot.md +++ b/docs/sources/http_api/snapshot.md @@ -17,6 +17,7 @@ parent = "http_api" **Example Request**: +```http POST /api/snapshots HTTP/1.1 Accept: application/json Content-Type: application/json @@ -51,18 +52,20 @@ parent = "http_api" }, "expires": 3600 } +``` JSON Body schema: - **dashboard** – Required. The complete dashboard model. - **name** – Optional. snapshot name -- **expires** - Optional. When the snapshot should expire in seconds. 3600 is 1 hour, 86400 is 1 day. Default is never to expire. +- **expires** - Optional. When the snapshot should expire in seconds. 3600 is 1 hour, 86400 is 1 day. Default is never to expire. - **external** - Optional. Save the snapshot on an external server rather than locally. Default is `false`. - **key** - Optional. Define the unique key. Required if **external** is `true`. - **deleteKey** - Optional. Unique key used to delete the snapshot. It is different from the **key** so that only the creator can delete the snapshot. Required if **external** is `true`. **Example Response**: +```http HTTP/1.1 200 Content-Type: application/json { @@ -71,6 +74,7 @@ JSON Body schema: "key":"YYYYYYY", "url":"myurl/dashboard/snapshot/YYYYYYY" } +``` Keys: @@ -83,54 +87,58 @@ Keys: **Example Request**: - GET /api/snapshots/YYYYYYY HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/snapshots/YYYYYYY HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - { - "meta":{ - "isSnapshot":true, - "type":"snapshot", - "canSave":false, - "canEdit":false, - "canStar":false, - "slug":"", - "expires":"2200-13-32T25:23:23+02:00", - "created":"2200-13-32T28:24:23+02:00" - }, - "dashboard": { - "editable":false, - "hideControls":true, - "nav":[ - { - "enable":false, - "type":"timepicker" - } - ], - "rows": [ - { +{ + "meta":{ + "isSnapshot":true, + "type":"snapshot", + "canSave":false, + "canEdit":false, + "canStar":false, + "slug":"", + "expires":"2200-13-32T25:23:23+02:00", + "created":"2200-13-32T28:24:23+02:00" + }, + "dashboard": { + "editable":false, + "hideControls":true, + "nav": [ + { + "enable":false, + "type":"timepicker" + } + ], + "rows": [ + { - } - ], - "style":"dark", - "tags":[], - "templating":{ - "list":[ - ] - }, - "time":{ - }, - "timezone":"browser", - "title":"Home", - "version":5 - } - } + } + ], + "style":"dark", + "tags":[], + "templating":{ + "list":[ + ] + }, + "time":{ + }, + "timezone":"browser", + "title":"Home", + "version":5 + } +} +``` ## Delete Snapshot by Id @@ -138,14 +146,18 @@ Keys: **Example Request**: - GET /api/snapshots/YYYYYYY HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/snapshots/YYYYYYY HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"Snapshot deleted. It might take an hour before it's cleared from a CDN cache."} +{"message":"Snapshot deleted. It might take an hour before it's cleared from a CDN cache."} +``` \ No newline at end of file diff --git a/docs/sources/http_api/user.md b/docs/sources/http_api/user.md index 761ac938cd8..ba8afd4db22 100644 --- a/docs/sources/http_api/user.md +++ b/docs/sources/http_api/user.md @@ -17,34 +17,38 @@ parent = "http_api" **Example Request**: - GET /api/users HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Basic YWRtaW46YWRtaW4= +```http +GET /api/users HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= +``` Default value for the `perpage` parameter is `1000` and for the `page` parameter is `1`. Requires basic authentication and that the authenticated user is a Grafana Admin. **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - [ - { - "id": 1, - "name": "Admin", - "login": "admin", - "email": "admin@mygraf.com", - "isAdmin": true - }, - { - "id": 2, - "name": "User", - "login": "user", - "email": "user@mygraf.com", - "isAdmin": false - } - ] +[ + { + "id": 1, + "name": "Admin", + "login": "admin", + "email": "admin@mygraf.com", + "isAdmin": true + }, + { + "id": 2, + "name": "User", + "login": "user", + "email": "user@mygraf.com", + "isAdmin": false + } +] +``` ## Search Users with Paging @@ -52,10 +56,12 @@ Default value for the `perpage` parameter is `1000` and for the `page` parameter **Example Request**: - GET /api/users/search?perpage=10&page=1&query=mygraf HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Basic YWRtaW46YWRtaW4= +```http +GET /api/users/search?perpage=10&page=1&query=mygraf HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= +``` Default value for the `perpage` parameter is `1000` and for the `page` parameter is `1`. The `totalCount` field in the response can be used for pagination of the user list E.g. if `totalCount` is equal to 100 users and the `perpage` parameter is set to 10 then there are 10 pages of users. The `query` parameter is optional and it will return results where the query value is contained in one of the `name`, `login` or `email` fields. Query values with spaces need to be url encoded e.g. `query=Jane%20Doe`. @@ -63,29 +69,31 @@ Requires basic authentication and that the authenticated user is a Grafana Admin **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json +{ + "totalCount": 2, + "users": [ { - "totalCount": 2, - "users": [ - { - "id": 1, - "name": "Admin", - "login": "admin", - "email": "admin@mygraf.com", - "isAdmin": true - }, - { - "id": 2, - "name": "User", - "login": "user", - "email": "user@mygraf.com", - "isAdmin": false - } - ], - "page": 1, - "perPage": 10 + "id": 1, + "name": "Admin", + "login": "admin", + "email": "admin@mygraf.com", + "isAdmin": true + }, + { + "id": 2, + "name": "User", + "login": "user", + "email": "user@mygraf.com", + "isAdmin": false } + ], + "page": 1, + "perPage": 10 +} +``` ## Get single user by Id @@ -93,26 +101,29 @@ Requires basic authentication and that the authenticated user is a Grafana Admin **Example Request**: - GET /api/users/1 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Basic YWRtaW46YWRtaW4= - +```http +GET /api/users/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= +``` Requires basic authentication and that the authenticated user is a Grafana Admin. **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - { - "email": "user@mygraf.com" - "name": "admin", - "login": "admin", - "theme": "light", - "orgId": 1, - "isGrafanaAdmin": true - } +{ + "email": "user@mygraf.com" + "name": "admin", + "login": "admin", + "theme": "light", + "orgId": 1, + "isGrafanaAdmin": true +} +``` ## Get single user by Username(login) or Email @@ -120,34 +131,39 @@ Requires basic authentication and that the authenticated user is a Grafana Admin **Example Request using the email as option**: - GET /api/users/lookup?loginOrEmail=user@mygraf.com HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/users/lookup?loginOrEmail=user@mygraf.com HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Request using the username as option**: - - GET /api/users/lookup?loginOrEmail=admin HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Basic YWRtaW46YWRtaW4= + +```http +GET /api/users/lookup?loginOrEmail=admin HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= +``` Requires basic authentication and that the authenticated user is a Grafana Admin. **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - - { - "email": "user@mygraf.com" - "name": "admin", - "login": "admin", - "theme": "light", - "orgId": 1, - "isGrafanaAdmin": true - } +```http +HTTP/1.1 200 +Content-Type: application/json +{ + "email": "user@mygraf.com" + "name": "admin", + "login": "admin", + "theme": "light", + "orgId": 1, + "isGrafanaAdmin": true +} +``` ## User Update @@ -155,27 +171,30 @@ Requires basic authentication and that the authenticated user is a Grafana Admin **Example Request**: - PUT /api/users/2 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Basic YWRtaW46YWRtaW4= +```http +PUT /api/users/2 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= - { - "email":"user@mygraf.com", - "name":"User2", - "login":"user", - "theme":"light" - } +{ + "email":"user@mygraf.com", + "name":"User2", + "login":"user", + "theme":"light" +} +``` Requires basic authentication and that the authenticated user is a Grafana Admin. **Example Response**: - HTTP/1.1 200 - Content-Type: application/json - - {"message":"User updated"} +```http +HTTP/1.1 200 +Content-Type: application/json +{"message":"User updated"} +``` ## Get Organisations for user @@ -183,25 +202,29 @@ Requires basic authentication and that the authenticated user is a Grafana Admin **Example Request**: - GET /api/users/1/orgs HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Basic YWRtaW46YWRtaW4= +```http +GET /api/users/1/orgs HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= +``` Requires basic authentication and that the authenticated user is a Grafana Admin. **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - [ - { - "orgId":1, - "name":"Main Org.", - "role":"Admin" - } - ] +[ + { + "orgId":1, + "name":"Main Org.", + "role":"Admin" + } +] +``` ## User @@ -211,24 +234,28 @@ Requires basic authentication and that the authenticated user is a Grafana Admin **Example Request**: - GET /api/user HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/user HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - { - "email":"admin@mygraf.com", - "name":"Admin", - "login":"admin", - "theme":"light", - "orgId":1, - "isGrafanaAdmin":true - } +{ + "email":"admin@mygraf.com", + "name":"Admin", + "login":"admin", + "theme":"light", + "orgId":1, + "isGrafanaAdmin":true +} +``` ## Change Password @@ -238,23 +265,27 @@ Changes the password for the user **Example Request**: - PUT /api/user/password HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +PUT /api/user/password HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - { - "oldPassword": "old_password", - "newPassword": "new_password", - "confirmNew": "confirm_new_password" - } +{ + "oldPassword": "old_password", + "newPassword": "new_password", + "confirmNew": "confirm_new_password" +} +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"User password changed"} +{"message":"User password changed"} +``` ## Switch user context for a specified user @@ -264,15 +295,19 @@ Switch user context to the given organization. Requires basic authentication and **Example Request**: - POST /api/users/7/using/2 HTTP/1.1 - Authorization: Basic YWRtaW46YWRtaW4= +```http +POST /api/users/7/using/2 HTTP/1.1 +Authorization: Basic YWRtaW46YWRtaW4= +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"Active organization changed"} +{"message":"Active organization changed"} +``` ## Switch user context for signed in user @@ -282,17 +317,21 @@ Switch user context to the given organization. **Example Request**: - POST /api/user/using/2 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +POST /api/user/using/2 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"Active organization changed"} +{"message":"Active organization changed"} +``` ## Organisations of the actual User @@ -302,23 +341,27 @@ Return a list of all organisations of the current user. **Example Request**: - GET /api/user/orgs HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +GET /api/user/orgs HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - [ - { - "orgId":1, - "name":"Main Org.", - "role":"Admin" - } - ] +[ + { + "orgId":1, + "name":"Main Org.", + "role":"Admin" + } +] +``` ## Star a dashboard @@ -328,17 +371,21 @@ Stars the given Dashboard for the actual user. **Example Request**: - POST /api/user/stars/dashboard/1 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +POST /api/user/stars/dashboard/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"Dashboard starred!"} +{"message":"Dashboard starred!"} +``` ## Unstar a dashboard @@ -348,14 +395,18 @@ Deletes the starring of the given Dashboard for the actual user. **Example Request**: - DELETE /api/user/stars/dashboard/1 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +```http +DELETE /api/user/stars/dashboard/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` **Example Response**: - HTTP/1.1 200 - Content-Type: application/json +```http +HTTP/1.1 200 +Content-Type: application/json - {"message":"Dashboard unstarred"} +{"message":"Dashboard unstarred"} +``` \ No newline at end of file diff --git a/docs/sources/installation/behind_proxy.md b/docs/sources/installation/behind_proxy.md index 0caa31bbfb5..3d89d8b3c2c 100644 --- a/docs/sources/installation/behind_proxy.md +++ b/docs/sources/installation/behind_proxy.md @@ -15,7 +15,7 @@ weight = 1 It should be straight forward to get Grafana up and running behind a reverse proxy. But here are some things that you might run into. Links and redirects will not be rendered correctly unless you set the server.domain setting. -``` +```bash [server] domain = foo.bar ``` @@ -28,14 +28,14 @@ Here are some example configurations for running Grafana behind a reverse proxy. ### Grafana configuration (ex http://foo.bar.com) -``` +```bash [server] domain = foo.bar ``` ### Nginx configuration -``` +```bash server { listen 80; root /usr/share/nginx/www; @@ -50,14 +50,14 @@ server { ### Examples with **sub path** (ex http://foo.bar.com/grafana) #### Grafana configuration with sub path -``` +```bash [server] domain = foo.bar root_url = %(protocol)s://%(domain)s:/grafana ``` #### Nginx configuration with sub path -``` +```bash server { listen 80; root /usr/share/nginx/www; diff --git a/docs/sources/installation/configuration.md b/docs/sources/installation/configuration.md index 6630825e803..370509f0a63 100644 --- a/docs/sources/installation/configuration.md +++ b/docs/sources/installation/configuration.md @@ -37,26 +37,31 @@ A common problem is forgetting to uncomment a line in the `custom.ini` (or `graf All options in the configuration file (listed below) can be overridden using environment variables using the syntax: - GF__ +```bash +GF__ +``` Where the section name is the text within the brackets. Everything should be upper case, `.` should be replaced by `_`. For example, given these configuration settings: - # default section - instance_name = ${HOSTNAME} +```bash +# default section +instance_name = ${HOSTNAME} - [security] - admin_user = admin - - [auth.google] - client_secret = 0ldS3cretKey +[security] +admin_user = admin +[auth.google] +client_secret = 0ldS3cretKey +``` Then you can override them using: - export GF_DEFAULT_INSTANCE_NAME=my-instance - export GF_SECURITY_ADMIN_USER=true - export GF_AUTH_GOOGLE_CLIENT_SECRET=newS3cretKey +```bash +export GF_DEFAULT_INSTANCE_NAME=my-instance +export GF_SECURITY_ADMIN_USER=true +export GF_AUTH_GOOGLE_CLIENT_SECRET=newS3cretKey +```
@@ -93,11 +98,15 @@ The IP address to bind to. If empty will bind to all interfaces The port to bind to, defaults to `3000`. To use port 80 you need to either give the Grafana binary permission for example: - $ sudo setcap 'cap_net_bind_service=+ep' /usr/sbin/grafana-server +```bash +$ sudo setcap 'cap_net_bind_service=+ep' /usr/sbin/grafana-server +``` Or redirect port 80 to the Grafana port using: - $ sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 3000 +```bash +$ sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 3000 +``` Another way is put a webserver like Nginx or Apache in front of Grafana and have them proxy requests to Grafana. @@ -312,7 +321,9 @@ You need to create a GitHub OAuth application (you find this under the GitHub settings page). When you create the application you will need to specify a callback URL. Specify this as callback: - http://:/login/github +```bash +http://:/login/github +``` This callback URL must match the full HTTP address that you use in your browser to access Grafana, but with the prefix path of `/login/github`. @@ -320,17 +331,19 @@ When the GitHub OAuth application is created you will get a Client ID and a Client Secret. Specify these in the Grafana configuration file. For example: - [auth.github] - enabled = true - allow_sign_up = true - client_id = YOUR_GITHUB_APP_CLIENT_ID - client_secret = YOUR_GITHUB_APP_CLIENT_SECRET - scopes = user:email - auth_url = https://github.com/login/oauth/authorize - token_url = https://github.com/login/oauth/access_token - api_url = https://api.github.com/user - team_ids = - allowed_organizations = +```bash +[auth.github] +enabled = true +allow_sign_up = true +client_id = YOUR_GITHUB_APP_CLIENT_ID +client_secret = YOUR_GITHUB_APP_CLIENT_SECRET +scopes = user:email +auth_url = https://github.com/login/oauth/authorize +token_url = https://github.com/login/oauth/access_token +api_url = https://api.github.com/user +team_ids = +allowed_organizations = +``` Restart the Grafana back-end. You should now see a GitHub login button on the login page. You can now login or sign up with your GitHub @@ -348,15 +361,17 @@ GitHub. If the authenticated user isn't a member of at least one of the teams they will not be able to register or authenticate with your Grafana instance. For example: - [auth.github] - enabled = true - client_id = YOUR_GITHUB_APP_CLIENT_ID - client_secret = YOUR_GITHUB_APP_CLIENT_SECRET - scopes = user:email,read:org - team_ids = 150,300 - auth_url = https://github.com/login/oauth/authorize - token_url = https://github.com/login/oauth/access_token - allow_sign_up = true +```bash +[auth.github] +enabled = true +client_id = YOUR_GITHUB_APP_CLIENT_ID +client_secret = YOUR_GITHUB_APP_CLIENT_SECRET +scopes = user:email,read:org +team_ids = 150,300 +auth_url = https://github.com/login/oauth/authorize +token_url = https://github.com/login/oauth/access_token +allow_sign_up = true +``` ### allowed_organizations @@ -365,16 +380,18 @@ organizations on GitHub. If the authenticated user isn't a member of at least one of the organizations they will not be able to register or authenticate with your Grafana instance. For example - [auth.github] - enabled = true - client_id = YOUR_GITHUB_APP_CLIENT_ID - client_secret = YOUR_GITHUB_APP_CLIENT_SECRET - scopes = user:email,read:org - auth_url = https://github.com/login/oauth/authorize - token_url = https://github.com/login/oauth/access_token - allow_sign_up = true - # space-delimited organization names - allowed_organizations = github google +```bash +[auth.github] +enabled = true +client_id = YOUR_GITHUB_APP_CLIENT_ID +client_secret = YOUR_GITHUB_APP_CLIENT_SECRET +scopes = user:email,read:org +auth_url = https://github.com/login/oauth/authorize +token_url = https://github.com/login/oauth/access_token +allow_sign_up = true +# space-delimited organization names +allowed_organizations = github google +```
@@ -385,22 +402,26 @@ Developer Console](https://console.developers.google.com/project). When you create the project you will need to specify a callback URL. Specify this as callback: - http://:/login/google +```bash +http://:/login/google +``` This callback URL must match the full HTTP address that you use in your browser to access Grafana, but with the prefix path of `/login/google`. When the Google project is created you will get a Client ID and a Client Secret. Specify these in the Grafana configuration file. For example: - [auth.google] - enabled = true - client_id = YOUR_GOOGLE_APP_CLIENT_ID - client_secret = YOUR_GOOGLE_APP_CLIENT_SECRET - scopes = https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email - auth_url = https://accounts.google.com/o/oauth2/auth - token_url = https://accounts.google.com/o/oauth2/token - allowed_domains = mycompany.com mycompany.org - allow_sign_up = true +```bash +[auth.google] +enabled = true +client_id = YOUR_GOOGLE_APP_CLIENT_ID +client_secret = YOUR_GOOGLE_APP_CLIENT_SECRET +scopes = https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email +auth_url = https://accounts.google.com/o/oauth2/auth +token_url = https://accounts.google.com/o/oauth2/token +allowed_domains = mycompany.com mycompany.org +allow_sign_up = true +``` Restart the Grafana back-end. You should now see a Google login button on the login page. You can now login or sign up with your Google @@ -418,16 +439,18 @@ This option could be used if have your own oauth service. This callback URL must match the full HTTP address that you use in your browser to access Grafana, but with the prefix path of `/login/generic_oauth`. - [auth.generic_oauth] - enabled = true - client_id = YOUR_APP_CLIENT_ID - client_secret = YOUR_APP_CLIENT_SECRET - scopes = - auth_url = - token_url = - api_url = - allowed_domains = mycompany.com mycompany.org - allow_sign_up = true +```bash +[auth.generic_oauth] +enabled = true +client_id = YOUR_APP_CLIENT_ID +client_secret = YOUR_APP_CLIENT_SECRET +scopes = +auth_url = +token_url = +api_url = +allowed_domains = mycompany.com mycompany.org +allow_sign_up = true +``` Set api_url to the resource that returns [OpenID UserInfo](https://connect2id.com/products/server/docs/api/userinfo) compatible information. @@ -503,21 +526,25 @@ session table manually. Mysql Example: - CREATE TABLE `session` ( - `key` CHAR(16) NOT NULL, - `data` BLOB, - `expiry` INT(11) UNSIGNED NOT NULL, - PRIMARY KEY (`key`) - ) ENGINE=MyISAM DEFAULT CHARSET=utf8; +```bash +CREATE TABLE `session` ( + `key` CHAR(16) NOT NULL, + `data` BLOB, + `expiry` INT(11) UNSIGNED NOT NULL, + PRIMARY KEY (`key`) +) ENGINE=MyISAM DEFAULT CHARSET=utf8; +``` Postgres Example: - CREATE TABLE session ( - key CHAR(16) NOT NULL, - data BYTEA, - expiry INTEGER NOT NULL, - PRIMARY KEY (key) - ); +```bash +CREATE TABLE session ( + key CHAR(16) NOT NULL, + data BYTEA, + expiry INTEGER NOT NULL, + PRIMARY KEY (key) +); +``` Postgres valid `sslmode` are `disable`, `require` (default), `verify-ca`, and `verify-full`. @@ -698,7 +725,7 @@ Service Account keys can be created and downloaded from https://console.develope Service Account should have "Storage Object Writer" role. ### bucket name -Bucket Name on Google Cloud Storage. +Bucket Name on Google Cloud Storage. ## [alerting] diff --git a/docs/sources/installation/debian.md b/docs/sources/installation/debian.md index 330e3171e86..222a337855a 100644 --- a/docs/sources/installation/debian.md +++ b/docs/sources/installation/debian.md @@ -45,13 +45,17 @@ sudo dpkg -i grafana_4.5.2-beta1_amd64.deb Add the following line to your `/etc/apt/sources.list` file. - deb https://packagecloud.io/grafana/stable/debian/ jessie main +```bash +deb https://packagecloud.io/grafana/stable/debian/ jessie main +``` Use the above line even if you are on Ubuntu or another Debian version. There is also a testing repository if you want beta or release candidates. - deb https://packagecloud.io/grafana/testing/debian/ jessie main +```bash +deb https://packagecloud.io/grafana/testing/debian/ jessie main +``` Then add the [Package Cloud](https://packagecloud.io/grafana) key. This allows you to install signed packages. diff --git a/docs/sources/installation/docker.md b/docs/sources/installation/docker.md index 03e6979d72b..bfb754900fa 100644 --- a/docs/sources/installation/docker.md +++ b/docs/sources/installation/docker.md @@ -14,7 +14,9 @@ weight = 4 Grafana is very easy to install and run using the offical docker container. - $ docker run -d -p 3000:3000 grafana/grafana +```bash +$ docker run -d -p 3000:3000 grafana/grafana +``` All Grafana configuration settings can be defined using environment variables, this is especially useful when using the above container. @@ -26,10 +28,12 @@ folder `/var/lib/grafana` and configuration files is in `/etc/grafana/` folder. You can map these volumes to host folders when you start the container: - $ docker run -d -p 3000:3000 \ - -v /var/lib/grafana:/var/lib/grafana \ - -e "GF_SECURITY_ADMIN_PASSWORD=secret" \ - grafana/grafana +```bash +$ docker run -d -p 3000:3000 \ + -v /var/lib/grafana:/var/lib/grafana \ + -e "GF_SECURITY_ADMIN_PASSWORD=secret" \ + grafana/grafana +``` In the above example I map the data folder and sets a configuration option via an `ENV` instruction. diff --git a/docs/sources/installation/ldap.md b/docs/sources/installation/ldap.md index 769ca3fd1ba..8f6be6e1d8c 100644 --- a/docs/sources/installation/ldap.md +++ b/docs/sources/installation/ldap.md @@ -92,7 +92,7 @@ org_role = "Viewer" By default the configuration expects you to specify a bind DN and bind password. This should be a read only user that can perform LDAP searches. When the user DN is found a second bind is performed with the user provided username & password (in the normal Grafana login form). -``` +```bash bind_dn = "cn=admin,dc=grafana,dc=org" bind_password = "grafana" ``` @@ -102,7 +102,7 @@ bind_password = "grafana" If you can provide a single bind expression that matches all possible users, you can skip the second bind and bind against the user DN directly. This allows you to not specify a bind_password in the configuration file. -``` +```bash bind_dn = "cn=%s,o=users,dc=grafana,dc=org" ``` diff --git a/docs/sources/installation/mac.md b/docs/sources/installation/mac.md index a65c663f398..b1d4f18f699 100644 --- a/docs/sources/installation/mac.md +++ b/docs/sources/installation/mac.md @@ -15,7 +15,7 @@ Installation can be done using [homebrew](http://brew.sh/) Install latest stable: -``` +```bash brew update brew install grafana ``` @@ -24,7 +24,7 @@ To start grafana look at the command printed after the homebrew install complete To upgrade use the reinstall command -``` +```bash brew update brew reinstall grafana ``` @@ -34,13 +34,13 @@ brew reinstall grafana You can also install the latest unstable grafana from git: -``` +```bash brew install --HEAD grafana/grafana/grafana ``` To upgrade grafana if you've installed from HEAD: -``` +```bash brew reinstall --HEAD grafana/grafana/grafana ``` @@ -48,13 +48,13 @@ brew reinstall --HEAD grafana/grafana/grafana To start Grafana using homebrew services first make sure homebrew/services is installed. -``` +```bash brew tap homebrew/services ``` Then start Grafana using: -``` +```bash brew services start grafana ``` diff --git a/docs/sources/installation/rpm.md b/docs/sources/installation/rpm.md index 30b017314c6..b72e5c78d2f 100644 --- a/docs/sources/installation/rpm.md +++ b/docs/sources/installation/rpm.md @@ -26,41 +26,54 @@ installation. You can install Grafana using Yum directly. - $ sudo yum install https://s3-us-west-2.amazonaws.com/grafana-releases/release/grafana-4.5.2-1.x86_64.rpm +```bash +$ sudo yum install https://s3-us-west-2.amazonaws.com/grafana-releases/release/grafana-4.5.2-1.x86_64.rpm +``` Or install manually using `rpm`. #### On CentOS / Fedora / Redhat: - $ wget https://s3-us-west-2.amazonaws.com/grafana-releases/release/grafana-4.5.2-1.x86_64.rpm - $ sudo yum install initscripts fontconfig - $ sudo rpm -Uvh grafana-4.5.2-1.x86_64.rpm +```bash +$ wget https://s3-us-west-2.amazonaws.com/grafana-releases/release/grafana-4.5.2-1.x86_64.rpm +$ sudo yum install initscripts fontconfig +$ sudo rpm -Uvh grafana-4.5.2-1.x86_64.rpm +``` #### On OpenSuse: - $ sudo rpm -i --nodeps grafana-4.5.2-1.x86_64.rpm +```bash +$ sudo rpm -i --nodeps grafana-4.5.2-1.x86_64.rpm +``` ## Install via YUM Repository Add the following to a new file at `/etc/yum.repos.d/grafana.repo` - [grafana] - name=grafana - baseurl=https://packagecloud.io/grafana/stable/el/6/$basearch - repo_gpgcheck=1 - enabled=1 - gpgcheck=1 - gpgkey=https://packagecloud.io/gpg.key https://grafanarel.s3.amazonaws.com/RPM-GPG-KEY-grafana - sslverify=1 - sslcacert=/etc/pki/tls/certs/ca-bundle.crt +```bash +[grafana] +name=grafana +baseurl=https://packagecloud.io/grafana/stable/el/6/$basearch +repo_gpgcheck=1 +enabled=1 +gpgcheck=1 +gpgkey=https://packagecloud.io/gpg.key +https://grafanarel.s3.amazonaws.com/RPM-GPG-KEY-grafana +sslverify=1 +sslcacert=/etc/pki/tls/certs/ca-bundle.crt +``` There is also a testing repository if you want beta or release candidates. - baseurl=https://packagecloud.io/grafana/testing/el/6/$basearch +```bash +baseurl=https://packagecloud.io/grafana/testing/el/6/$basearch +``` Then install Grafana via the `yum` command. - $ sudo yum install grafana +```bash +$ sudo yum install grafana +``` ### RPM GPG Key @@ -81,7 +94,9 @@ key](https://grafanarel.s3.amazonaws.com/RPM-GPG-KEY-grafana). You can start Grafana by running: - $ sudo service grafana-server start +```bash +$ sudo service grafana-server start +``` This will start the `grafana-server` process as the `grafana` user, which is created during package installation. The default HTTP port is @@ -89,17 +104,23 @@ which is created during package installation. The default HTTP port is To configure the Grafana server to start at boot time: - $ sudo /sbin/chkconfig --add grafana-server +```bash +$ sudo /sbin/chkconfig --add grafana-server +``` ## Start the server (via systemd) - $ systemctl daemon-reload - $ systemctl start grafana-server - $ systemctl status grafana-server +```bash +$ systemctl daemon-reload +$ systemctl start grafana-server +$ systemctl status grafana-server +``` ### Enable the systemd service to start at boot - sudo systemctl enable grafana-server.service +```bash +sudo systemctl enable grafana-server.service +``` ## Environment file @@ -138,7 +159,7 @@ for example in alert notifications. If the image is missing text make sure you have font packages installed. -``` +```bash yum install fontconfig yum install freetype* yum install urw-fonts diff --git a/docs/sources/installation/upgrading.md b/docs/sources/installation/upgrading.md index 4cd8471e441..6a4b4e8f047 100644 --- a/docs/sources/installation/upgrading.md +++ b/docs/sources/installation/upgrading.md @@ -29,7 +29,7 @@ installed grafana to custom location using a binary tar/zip it is usally in ` mysqldump -u root -p[root_password] [grafana] > grafana_backup.sql @@ -39,7 +39,7 @@ restore: #### postgres -``` +```bash backup: > pg_dump grafana > grafana_backup @@ -54,7 +54,7 @@ and execute the same `dpkg -i` command but with the new package. It will upgrade If you used our APT repository: -``` +```bash sudo apt-get update sudo apt-get install grafana ``` @@ -73,14 +73,14 @@ and execute the same `yum install` or `rpm -i` command but with the new package. If you used our YUM repository: -``` +```bash sudo yum update grafana ``` ### Docker This just an example, details depend on how you configured your grafana container. -``` +```bash docker pull grafana docker stop my-grafana-container docker rm my-grafana-container diff --git a/docs/sources/plugins/developing/code-styleguide.md b/docs/sources/plugins/developing/code-styleguide.md index 44379c4d4e5..9ee91412e24 100644 --- a/docs/sources/plugins/developing/code-styleguide.md +++ b/docs/sources/plugins/developing/code-styleguide.md @@ -23,7 +23,7 @@ The most important fields are the first three, especially the id. The convention Examples: -``` +```bash raintank-worldping-app grafana-simple-json-datasource grafana-piechart-panel @@ -66,7 +66,7 @@ The README.md file is rendered both on Grafana.net and in the plugins section in Here is a typical directory structure for a plugin. -``` +```bash johnnyb-awesome-datasource |-- dist |-- spec diff --git a/docs/sources/plugins/developing/datasources.md b/docs/sources/plugins/developing/datasources.md index 612a0786976..0149f06e1aa 100644 --- a/docs/sources/plugins/developing/datasources.md +++ b/docs/sources/plugins/developing/datasources.md @@ -45,7 +45,7 @@ The javascript object that communicates with the database and transforms data to The Datasource should contain the following functions: -``` +```javascript query(options) //used by panels to get data testDatasource() //used by datasource configuration page to make sure the connection is working annotationQuery(options) // used by dashboards to get annotations diff --git a/docs/sources/plugins/installation.md b/docs/sources/plugins/installation.md index 27f6f583d9a..526f1d5d4eb 100644 --- a/docs/sources/plugins/installation.md +++ b/docs/sources/plugins/installation.md @@ -30,37 +30,37 @@ On Linux systems the grafana-cli will assume that the grafana plugin directory i ### Grafana-cli Commands List available plugins -``` +```bash grafana-cli plugins list-remote ``` Install the latest version of a plugin -``` +```bash grafana-cli plugins install ``` Install a specific version of a plugin -``` +```bash grafana-cli plugins install ``` List installed plugins -``` +```bash grafana-cli plugins ls ``` Update all installed plugins -``` +```bash grafana-cli plugins update-all ``` Update one plugin -``` +```bash grafana-cli plugins update ``` Remove one plugin -``` +```bash grafana-cli plugins remove ``` @@ -73,7 +73,7 @@ The Download URL from Grafana.com API is in this form: `https://grafana.com/api/plugins//versions//download` You can specify a local URL by using the `--pluginUrl` option. -``` +```bash grafana-cli --pluginUrl https://nexus.company.com/grafana/plugins/-.zip plugins install ``` @@ -84,7 +84,7 @@ To manually install a Plugin via the Grafana.com API: {{< imgbox img="/img/docs/installation-tab.png" caption="Installation Tab" >}} 2. Use the Grafana API to find the plugin using this url `https://grafana.com/api/plugins/`. For example: https://grafana.com/api/plugins/jdbranham-diagram-panel should return: - ``` + ```bash { "id": 145, "typeId": 3, @@ -97,7 +97,7 @@ To manually install a Plugin via the Grafana.com API: ``` 3. Find the download link: - ``` + ```bash { "rel": "download", "href": "/plugins/jdbranham-diagram-panel/versions/1.4.0/download" diff --git a/docs/sources/project/building_from_source.md b/docs/sources/project/building_from_source.md index f8dcc9a949c..1e4f0421a0c 100644 --- a/docs/sources/project/building_from_source.md +++ b/docs/sources/project/building_from_source.md @@ -20,20 +20,20 @@ dev environment. Grafana ships with its own required backend server; also comple ## Get Code Create a directory for the project and set your path accordingly (or use the [default Go workspace directory](https://golang.org/doc/code.html#GOPATH)). Then download and install Grafana into your $GOPATH directory: -``` +```bash export GOPATH=`pwd` go get github.com/grafana/grafana ``` On Windows use setx instead of export and then restart your command prompt: -``` +```bash setx GOPATH %cd% ``` You may see an error such as: `package github.com/grafana/grafana: no buildable Go source files`. This is just a warning, and you can proceed with the directions. ## Building the backend -``` +```bash cd $GOPATH/src/github.com/grafana/grafana go run build.go setup go run build.go build # (or 'go build ./pkg/cmd/grafana-server') @@ -45,7 +45,7 @@ to install GCC. We recommend [TDM-GCC](http://tdm-gcc.tdragon.net/download). [node-gyp](https://github.com/nodejs/node-gyp#installation) is the Node.js native addon build tool and it requires extra dependencies to be installed on Windows. In a command prompt which is run as administrator, run: -``` +```bash npm --add-python-to-path='true' --debug install --global windows-build-tools ``` @@ -53,7 +53,7 @@ npm --add-python-to-path='true' --debug install --global windows-build-tools For this you need nodejs (v.6+). -``` +```bash npm install -g yarn yarn install --pure-lockfile npm run build @@ -62,7 +62,7 @@ npm run build ## Running Grafana Locally You can run a local instance of Grafana by running: -``` +```bash ./bin/grafana-server ``` If you built the binary with `go run build.go build`, run `./bin/grafana-server` @@ -76,7 +76,7 @@ Open grafana in your browser (default [http://localhost:3000](http://localhost:3 To add features, customize your config, etc, you'll need to rebuild the backend when you change the source code. We use a tool named `bra` that does this. -``` +```bash go get github.com/Unknwon/bra bra run @@ -88,7 +88,7 @@ You'll also need to run `npm run watch` to watch for changes to the front-end (t This step builds linux packages and requires that fpm is installed. Install fpm via `gem install fpm`. -``` +```bash go run build.go build package ``` diff --git a/docs/sources/reference/dashboard.md b/docs/sources/reference/dashboard.md index 3bbecfcef4d..d2da621a5a3 100644 --- a/docs/sources/reference/dashboard.md +++ b/docs/sources/reference/dashboard.md @@ -24,7 +24,7 @@ When a user creates a new dashboard, a new dashboard JSON object is initialized > Note: In the following JSON, id is shown as null which is the default value assigned to it until a dashboard is saved. Once a dashboard is saved, an integer value is assigned to the `id` field. -``` +```json { "id": null, "title": "New dashboard", diff --git a/docs/sources/reference/sharing.md b/docs/sources/reference/sharing.md index 61ae1f761eb..badd3b5712a 100644 --- a/docs/sources/reference/sharing.md +++ b/docs/sources/reference/sharing.md @@ -43,7 +43,7 @@ You also get a link to service side rendered PNG of the panel. Useful if you wan Example of a link to a server-side rendered PNG: -``` +```bash http://play.grafana.org/render/dashboard-solo/db/grafana-play-home?orgId=1&panelId=4&from=1499272191563&to=1499279391563&width=1000&height=500&tz=UTC%2B02%3A00&timeout=5000 ``` diff --git a/docs/sources/tutorials/api_org_token_howto.md b/docs/sources/tutorials/api_org_token_howto.md index e985b499dbe..984cfd40bd0 100644 --- a/docs/sources/tutorials/api_org_token_howto.md +++ b/docs/sources/tutorials/api_org_token_howto.md @@ -22,24 +22,24 @@ Some parts of the API are only available through basic authentication and these The task is to create a new organization and then add a Token that can be used by other users. In the examples below which use basic auth, the user is `admin` and the password is `admin`. 1. [Create the org](http://docs.grafana.org/http_api/org/#create-organisation). Here is an example using curl: - ``` + ```bash curl -X POST -H "Content-Type: application/json" -d '{"name":"apiorg"}' http://admin:admin@localhost:3000/api/orgs ``` This should return a response: `{"message":"Organization created","orgId":6}`. Use the orgId for the next steps. 2. Optional step. If the org was created previously and/or step 3 fails then first [add your Admin user to the org](http://docs.grafana.org/http_api/org/#add-user-in-organisation): - ``` + ```bash curl -X POST -H "Content-Type: application/json" -d '{"loginOrEmail":"admin", "role": "Admin"}' http://admin:admin@localhost:3000/api/orgs//users ``` 3. [Switch the org context for the Admin user to the new org](http://docs.grafana.org/http_api/user/#switch-user-context): - ``` + ```bash curl -X POST http://admin:admin@localhost:3000/api/user/using/ ``` 4. [Create the API token](http://docs.grafana.org/http_api/auth/#create-api-key): - ``` + ```bash curl -X POST -H "Content-Type: application/json" -d '{"name":"apikeycurl", "role": "Admin"}' http://admin:admin@localhost:3000/api/auth/keys ``` @@ -49,11 +49,11 @@ The task is to create a new organization and then add a Token that can be used b ## How To Add A Dashboard -Using the Token that was created in the previous step, you can create a dashboard or carry out other actions without having to switch organizations. +Using the Token that was created in the previous step, you can create a dashboard or carry out other actions without having to switch organizations. 1. [Add a dashboard](http://docs.grafana.org/http_api/dashboard/#create-update-dashboard) using the key (or bearer token as it is also called): - ``` + ```bash curl -X POST --insecure -H "Authorization: Bearer eyJrIjoiR0ZXZmt1UFc0OEpIOGN5RWdUalBJTllUTk83VlhtVGwiLCJuIjoiYXBpa2V5Y3VybCIsImlkIjo2fQ==" -H "Content-Type: application/json" -d '{ "dashboard": { "id": null, diff --git a/docs/sources/tutorials/hubot_howto.md b/docs/sources/tutorials/hubot_howto.md index 58c902951ee..2f122e5b4e2 100644 --- a/docs/sources/tutorials/hubot_howto.md +++ b/docs/sources/tutorials/hubot_howto.md @@ -39,9 +39,9 @@ read the official [Getting Started With Hubot](https://hubot.github.com/docs/) g ## Install Hubot-Grafana script In your Hubot project repo install the Grafana plugin using `npm`: - - npm install hubot-grafana --save - +```bash +npm install hubot-grafana --save +``` Edit the file external-scripts.json, and add hubot-grafana to the list of plugins. ```json @@ -56,13 +56,15 @@ Edit the file external-scripts.json, and add hubot-grafana to the list of plugin The `hubot-grafana` plugin requires a number of environment variables to be set in order to work properly. - export HUBOT_GRAFANA_HOST=http://play.grafana.org - export HUBOT_GRAFANA_API_KEY=abcd01234deadbeef01234 - export HUBOT_GRAFANA_S3_BUCKET=mybucket - export HUBOT_GRAFANA_S3_ACCESS_KEY_ID=ABCDEF123456XYZ - export HUBOT_GRAFANA_S3_SECRET_ACCESS_KEY=aBcD01234dEaDbEef01234 - export HUBOT_GRAFANA_S3_PREFIX=graphs - export HUBOT_GRAFANA_S3_REGION=us-standard +```bash +export HUBOT_GRAFANA_HOST=http://play.grafana.org +export HUBOT_GRAFANA_API_KEY=abcd01234deadbeef01234 +export HUBOT_GRAFANA_S3_BUCKET=mybucket +export HUBOT_GRAFANA_S3_ACCESS_KEY_ID=ABCDEF123456XYZ +export HUBOT_GRAFANA_S3_SECRET_ACCESS_KEY=aBcD01234dEaDbEef01234 +export HUBOT_GRAFANA_S3_PREFIX=graphs +export HUBOT_GRAFANA_S3_REGION=us-standard +``` ### Grafana server side rendering @@ -112,7 +114,9 @@ can create hubot command aliases with the hubot script `hubot-alias`. Install it: - npm i --save hubot-alias +```bash +npm i --save hubot-alias +``` Now add `hubot-alias` to the list of plugins in `external-scripts.json` and restart hubot.