From 952e4dab3e463a4c0c32b509032b9371f96a7038 Mon Sep 17 00:00:00 2001 From: utkarshcmu Date: Tue, 2 Feb 2016 22:59:22 -0800 Subject: [PATCH 1/3] Arranged http_api docs in a better way --- docs/sources/http_api/admin.md | 274 +++++ docs/sources/http_api/dashboards.md | 261 +++++ docs/sources/http_api/data_sources.md | 190 +++ docs/sources/http_api/first_steps.md | 43 + docs/sources/http_api/general.md | 71 ++ docs/sources/http_api/orgs.md | 343 ++++++ docs/sources/http_api/snapshots.md | 137 +++ docs/sources/http_api/users.md | 254 ++++ docs/sources/reference/http_api.md | 1534 ------------------------- 9 files changed, 1573 insertions(+), 1534 deletions(-) create mode 100644 docs/sources/http_api/admin.md create mode 100644 docs/sources/http_api/dashboards.md create mode 100644 docs/sources/http_api/data_sources.md create mode 100644 docs/sources/http_api/first_steps.md create mode 100644 docs/sources/http_api/general.md create mode 100644 docs/sources/http_api/orgs.md create mode 100644 docs/sources/http_api/snapshots.md create mode 100644 docs/sources/http_api/users.md delete mode 100644 docs/sources/reference/http_api.md diff --git a/docs/sources/http_api/admin.md b/docs/sources/http_api/admin.md new file mode 100644 index 00000000000..4688b4f5d9f --- /dev/null +++ b/docs/sources/http_api/admin.md @@ -0,0 +1,274 @@ +---- +page_title: Admin APIs +page_description: Grafana Admin API Reference +page_keywords: grafana, admin, http, api, documentation +--- + +## Admin API + +### Settings + +`GET /api/admin/settings` + +**Example Request**: + + GET /api/admin/settings + Accept: application/json + Content-Type: application/json + Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +**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", + "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", + "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` + +**Example Request**: + + GET /api/admin/stats + Accept: application/json + Content-Type: application/json + Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +**Example Response**: + + 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 + } + +### Global Users + +`POST /api/admin/users` + +Create new user + +**Example Request**: + + POST /api/admin/users HTTP/1.1 + Accept: application/json + Content-Type: application/json + Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + + { + "name":"User", + "email":"user@graf.com", + "login":"user", + "password":"userpassword" + } + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + {"id":5,"message":"User created"} + +### Password for User + +`PUT /api/admin/users/:id/password` + +Change password for specific user + +**Example Request**: + + PUT /api/admin/users/2/password HTTP/1.1 + Accept: application/json + Content-Type: application/json + Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + {"password":"userpassword"} + +### Permissions + +`PUT /api/admin/users/:id/permissions` + +**Example Request**: + + PUT /api/admin/users/2/permissions 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 permissions updated"} + +### Delete global User + +`DELETE /api/admin/users/:id` + +**Example Request**: + + DELETE /api/admin/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 + + {message: "User deleted"} \ No newline at end of file diff --git a/docs/sources/http_api/dashboards.md b/docs/sources/http_api/dashboards.md new file mode 100644 index 00000000000..e1cbf6e436f --- /dev/null +++ b/docs/sources/http_api/dashboards.md @@ -0,0 +1,261 @@ +---- +page_title: Dashboards API +page_description: Grafana Dashboards API Reference +page_keywords: grafana, admin, http, api, documentation, dashboards +--- + +## Dashboards API + +### Create / Update dashboard + +`POST /api/dashboards/db` + +Creates a new dashboard or updates an existing dashboard. + +**Example Request for new dashboard**: + + POST /api/dashboards/db HTTP/1.1 + Accept: application/json + Content-Type: application/json + Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + + { + "dashboard": { + "id": null, + "title": "Production Overview", + "tags": [ "templated" ], + "timezone": "browser", + "rows": [ + { + } + ], + "schemaVersion": 6, + "version": 0 + }, + "overwrite": false + } + +JSON Body schema: + +- **dashboard** – The complete dashboard model, id = null to create a new dashboard +- **overwrite** – Set to true if you want to overwrite existing dashboard with newer version or with same dashboard title. + +**Example Response**: + + HTTP/1.1 200 OK + Content-Type: application/json; charset=UTF-8 + Content-Length: 78 + + { + "slug": "production-overview", + "status": "success", + "version": 1 + } + +Status Codes: + +- **200** – Created +- **400** – Errors (invalid json, missing or invalid fields, etc) +- **401** – Unauthorized +- **412** – Precondition failed + +The **412** status code is used when a newer dashboard already exists (newer, its version is greater than the version that was sent). The +same status code is also used if another dashboard exists with the same title. The response body will look like this: + + HTTP/1.1 412 Precondition Failed + Content-Type: application/json; charset=UTF-8 + Content-Length: 97 + + { + "message": "The dashboard has been changed by someone else", + "status": "version-mismatch" + } + +In in case of title already exists the `status` property will be `name-exists`. + +### Get dashboard + +`GET /api/dashboards/db/:slug` + +Will return the dashboard given the dashboard slug. Slug is the url friendly version of the dashboard title. + +**Example Request**: + + GET /api/dashboards/db/production-overview HTTP/1.1 + Accept: application/json + Content-Type: application/json + Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + { + "meta": { + "isStarred": false, + "slug": "production-overview" + }, + "model": { + "id": null, + "title": "Production Overview", + "tags": [ "templated" ], + "timezone": "browser", + "rows": [ + { + } + ], + "schemaVersion": 6, + "version": 0 + } + } + +### Delete dashboard + +`DELETE /api/dashboards/db/:slug` + +The above will delete the dashboard with the specified slug. The slug is the url friendly (unique) version of the dashboard title. + +**Example Request**: + + DELETE /api/dashboards/db/test HTTP/1.1 + Accept: application/json + Content-Type: application/json + Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + {"title": "Test"} + +### Gets the home dashboard + +`GET /api/dashboards/home` + +Will return the home dashboard. + +**Example Request**: + + 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 + + { + "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 + } + } + +### Tags for Dashboard + + +`GET /api/dashboards/tags` + +Get all tabs of dashboards + +**Example Request**: + + 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 + + [ + { + "term":"tag1", + "count":1 + }, + { + "term":"tag2", + "count":4 + } + ] + +### Dashboard from JSON file + +`GET /file/:file` + +### Search Dashboards + +`GET /api/search/` + +Status Codes: + +- **query** – Search Query +- **tags** – Tags to use +- **starred** – Flag indicating if only starred Dashboards should be returned +- **tagcloud** - Flag indicating if a tagcloud should be returned + +**Example Request**: + + 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 + + [ + { + "id":1, + "title":"Production Overview", + "uri":"db/production-overview", + "type":"dash-db", + "tags":[], + "isStarred":false + } + ] + + "email":"admin@mygraf.com", + "login":"admin", + "role":"Admin" + } + ] diff --git a/docs/sources/http_api/data_sources.md b/docs/sources/http_api/data_sources.md new file mode 100644 index 00000000000..8e2bc4e88de --- /dev/null +++ b/docs/sources/http_api/data_sources.md @@ -0,0 +1,190 @@ +---- +page_title: Data sources API +page_description: Grafana Data sources API Reference +page_keywords: grafana, admin, http, api, documentation, datasources +--- + +## Data sources API + +### Get all datasources + +`GET /api/datasources` + +**Example Request**: + + 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 + + [ + { + "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 + +`GET /api/datasources/:datasourceId` + +**Example Request**: + + 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 + + { + "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 + } + +### Create data source + +`POST /api/datasources` + +**Example Request**: + + 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 + } + + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + {"id":1,"message":"Datasource added"} + +### Update an existing data source + +`PUT /api/datasources/:datasourceId` + +**Example Request**: + + 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 + } + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + {"message":"Datasource updated"} + +### Delete an existing data source + +`DELETE /api/datasources/:datasourceId` + +**Example Request**: + + 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 + + {"message":"Data source deleted"} + +### Available data source types + +`GET /api/datasources/plugins` + +**Example Request**: + + GET /api/datasources/plugins HTTP/1.1 + Accept: application/json + Content-Type: application/json + Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + { + "grafana":{ + "metrics":true,"module":"plugins/datasource/grafana/datasource", + "name":"Grafana (for testing)", + "partials":{ + "query":"app/plugins/datasource/grafana/partials/query.editor.html" + }, + "pluginType":"datasource", + "serviceName":"GrafanaDatasource", + "type":"grafana" + } + } + +## Data source proxy calls + +`GET /api/datasources/proxy/:datasourceId/*` + +Proxies all calls to the actual datasource. diff --git a/docs/sources/http_api/first_steps.md b/docs/sources/http_api/first_steps.md new file mode 100644 index 00000000000..0fbdf348327 --- /dev/null +++ b/docs/sources/http_api/first_steps.md @@ -0,0 +1,43 @@ +---- +page_title: HTTP API +page_description: Grafana HTTP API Reference +page_keywords: grafana, admin, http, api, documentation +--- + +# HTTP API Reference + +The Grafana backend exposes an HTTP API, the same API is used by the frontend to do everything from saving +dashboards, creating users and updating data sources. + +## Authorization + +### Tokens + +Currently you can authenticate via an `API Token` or via a `Session cookie` (acquired using regular login or oauth). + +### Basic Auth + +If basic auth is enabled (it is enabled by default) you can authenticate your HTTP request via +standard basic auth. + +curl example: +``` +?curl http://admin:admin@localhost:3000/api/org +{"id":1,"name":"Main Org."} +``` + +### Create API Token + +Open the sidemenu and click the organization dropdown and select the `API Keys` option. + +![](/img/v2/orgdropdown_api_keys.png) + +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 + +The `Authorization` header value should be `Bearer `. \ No newline at end of file diff --git a/docs/sources/http_api/general.md b/docs/sources/http_api/general.md new file mode 100644 index 00000000000..d110851d9dc --- /dev/null +++ b/docs/sources/http_api/general.md @@ -0,0 +1,71 @@ +---- +page_title: General APIs +page_description: Grafana General API Reference +page_keywords: grafana, admin, http, api, documentation, dashboards +--- + +## Frontend Settings API + +### Get Settings + +`GET /api/frontend/settings` + +**Example Request**: + + 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 + + { + "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 + +### Renew session based on remember cookie + +`GET /api/login/ping` + +**Example Request**: + + 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 + + {"message": "Logged in"} \ No newline at end of file diff --git a/docs/sources/http_api/orgs.md b/docs/sources/http_api/orgs.md new file mode 100644 index 00000000000..9c378aaa06a --- /dev/null +++ b/docs/sources/http_api/orgs.md @@ -0,0 +1,343 @@ +---- +page_title: Organisations API +page_description: Grafana Organisations API Reference +page_keywords: grafana, admin, http, api, documentation, orgs, organisations +--- + +## Organisation API + +### Get current Organisation + +`GET /api/org` + +**Example Request**: + + 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 + + { + "id":1, + "name":"Main Org." + } + +### Get Organisation by Id + +`GET /api/orgs/:orgId` + +**Example Request**: + + 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":"" + } + } + +### 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 + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + { + "id":1, + "name":"Main Org.", + "address":{ + "address1":"", + "address2":"", + "city":"", + "zipCode":"", + "state":"", + "country":"" + } + } + +### Update current Organisation + +`PUT /api/org` + +**Example Request**: + + 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"} + + +### Get all users within the actual organisation + +`GET /api/org/users` + +**Example Request**: + + 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 + + [ + { + "orgId":1, + "userId":1, + "email":"admin@mygraf.com", + "login":"admin", + "role":"Admin" + } + ] + +### Add a new user to the actual organisation + +`POST /api/org/users` + +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" + } + + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + {"message":"User added to organization"} + +### Updates the given user + +`PATCH /api/org/users/:userId` + +**Example Request**: + + 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"} + + +### Delete user in actual organisation + +`DELETE /api/org/users/:userId` + +**Example Request**: + + 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"} + + +## Organisations + +### Search all Organisations + +`GET /api/orgs` + +**Example Request**: + + 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 + + [ + { + "id":1, + "name":"Main Org." + } + ] + +### Update Organisation + +`PUT /api/orgs/:orgId` + +Update Organisation, fields *Adress 1*, *Adress 2*, *City* are not implemented yet. + +**Example Request**: + + 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 + + {"message":"Organization updated"} + +### Get Users in Organisation + +`GET /api/orgs/:orgId/users` + +**Example Request**: + + 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" + } + ] + +### Add User in Organisation + +`POST /api/orgs/:orgId/users` + +**Example Request**: + + POST /api/orgs/1/users HTTP/1.1 + Accept: application/json + Content-Type: application/json + Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + + { + "loginOrEmail":"user", + "role":"Viewer" + } + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + {"message":"User added to organization"} + +### Update Users in Organisation + +`PATCH /api/orgs/:orgId/users/:userId` + +**Example Request**: + + PATCH /api/orgs/1/users/2 HTTP/1.1 + Accept: application/json + Content-Type: application/json + Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + + { + "role":"Admin" + } + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + {"message":"Organization user updated"} + +### Delete User in Organisation + +`DELETE /api/orgs/:orgId/users/:userId` + +**Example Request**: + + 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 + + {"message":"User removed from organization"} diff --git a/docs/sources/http_api/snapshots.md b/docs/sources/http_api/snapshots.md new file mode 100644 index 00000000000..cbfc28cd71b --- /dev/null +++ b/docs/sources/http_api/snapshots.md @@ -0,0 +1,137 @@ +---- +page_title: Snapshots API +page_description: Grafana Snapshots API Reference +page_keywords: grafana, admin, http, api, documentation, snapshots, dashboards +--- + +## Snapshots API + +### Create new snapshot + +`POST /api/snapshots` + +**Example Request**: + + POST /api/snapshots HTTP/1.1 + Accept: application/json + Content-Type: application/json + Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + + { + "dashboard": { + "editable":false, + "hideControls":true, + "nav":[ + { + "enable":false, + "type":"timepicker" + } + ], + "rows": [ + { + + } + ], + "style":"dark", + "tags":[], + "templating":{ + "list":[ + ] + }, + "time":{ + }, + "timezone":"browser", + "title":"Home", + "version":5 + }, + "expires": 3600 + } + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + { + "deleteKey":"XXXXXXX", + "deleteUrl":"myurl/dashboard/snapshot/XXXXXXX", + "key":"YYYYYYY", + "url":"myurl/dashboard/snapshot/YYYYYYY" + } + +Keys: + +- **deleteKey** – Key generated to delete the snapshot +- **key** – Key generated to share the dashboard + +### Get Snapshot by Id + +`GET /api/snapshots/:key` + +**Example Request**: + + 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 + + { + "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 + } + } + +### Delete Snapshot by Id + +`GET /api/snapshots-delete/:key` + +**Example Request**: + + 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 + + {"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/users.md b/docs/sources/http_api/users.md new file mode 100644 index 00000000000..6b6015d3018 --- /dev/null +++ b/docs/sources/http_api/users.md @@ -0,0 +1,254 @@ +---- +page_title: Users API +page_description: Grafana Users API Reference +page_keywords: grafana, admin, http, api, documentation, users +--- + +## Users API + +### Search Users + +`GET /api/users` + +**Example Request**: + + GET /api/users 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": "Admin", + "login": "admin", + "email": "admin@mygraf.com", + "isAdmin": true + }, + { + "id": 2, + "name": "User", + "login": "user", + "email": "user@mygraf.com", + "isAdmin": false + } + ] + +### Get single user by Id + +`GET /api/users/:id` + +**Example Request**: + + GET /api/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 + + { + "email": "user@mygraf.com" + "name": "admin", + "login": "admin", + "theme": "light", + "orgId": 1, + "isGrafanaAdmin": true + } + +### User Update + +`PUT /api/users/:id` + +**Example Request**: + + PUT /api/users/2 HTTP/1.1 + Accept: application/json + Content-Type: application/json + Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + + { + "email":"user@mygraf.com", + "name":"User2", + "login":"user", + "theme":"light" + } + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + {"message":"User updated"} + + +### Get Organisations for user + +`GET /api/users/:id/orgs` + +**Example Request**: + + GET /api/users/1/orgs 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, + "name":"Main Org.", + "role":"Admin" + } + ] + +## User + +### Actual User + +`GET /api/user` + +**Example Request**: + + 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 + + { + "email":"admin@mygraf.com", + "name":"Admin", + "login":"admin", + "theme":"light", + "orgId":1, + "isGrafanaAdmin":true + } + +### Change Password + +`PUT /api/user/password` + +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 + + { + "oldPassword": "old_password", + "newPassword": "new_password", + "confirmNew": "confirm_new_password" + } + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + {"message":"User password changed"} + +### Switch user context + +`POST /api/user/using/:organisationId` + +Switch user context to the given organisation. + +**Example Request**: + + 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 + + {"message":"Active organization changed"} + +### Organisations of the actual User + +`GET /api/user/orgs` + +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 + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + [ + { + "orgId":1, + "name":"Main Org.", + "role":"Admin" + } + ] + +### Star a dashboard + +`POST /api/user/stars/dashboard/:dashboardId` + +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 + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + {"message":"Dashboard starred!"} + +### Unstar a dashboard + +`DELETE /api/user/stars/dashboard/:dashboardId` + +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 + +**Example Response**: + + HTTP/1.1 200 + Content-Type: application/json + + {"message":"Dashboard unstarred"} \ No newline at end of file diff --git a/docs/sources/reference/http_api.md b/docs/sources/reference/http_api.md deleted file mode 100644 index 4b0dff6c4b6..00000000000 --- a/docs/sources/reference/http_api.md +++ /dev/null @@ -1,1534 +0,0 @@ ----- -page_title: HTTP API -page_description: Grafana HTTP API Reference -page_keywords: grafana, admin, http, api, documentation ---- - -# HTTP API Reference - -The Grafana backend exposes an HTTP API, the same API is used by the frontend to do everything from saving -dashboards, creating users and updating data sources. - -## Authorization - -### Tokens - -Currently you can authenticate via an `API Token` or via a `Session cookie` (acquired using regular login or oauth). - -### Basic Auth - -If basic auth is enabled (it is enabled by default) you can authenticate your HTTP request via -standard basic auth. - -curl example: -``` -?curl http://admin:admin@localhost:3000/api/org -{"id":1,"name":"Main Org."} -``` - -### Create API Token - -Open the sidemenu and click the organization dropdown and select the `API Keys` option. - -![](/img/v2/orgdropdown_api_keys.png) - -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 - -The `Authorization` header value should be `Bearer `. - -## Dashboards - -### Create / Update dashboard - -`POST /api/dashboards/db` - -Creates a new dashboard or updates an existing dashboard. - -**Example Request for new dashboard**: - - POST /api/dashboards/db HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "dashboard": { - "id": null, - "title": "Production Overview", - "tags": [ "templated" ], - "timezone": "browser", - "rows": [ - { - } - ], - "schemaVersion": 6, - "version": 0 - }, - "overwrite": false - } - -JSON Body schema: - -- **dashboard** – The complete dashboard model, id = null to create a new dashboard -- **overwrite** – Set to true if you want to overwrite existing dashboard with newer version or with same dashboard title. - -**Example Response**: - - HTTP/1.1 200 OK - Content-Type: application/json; charset=UTF-8 - Content-Length: 78 - - { - "slug": "production-overview", - "status": "success", - "version": 1 - } - -Status Codes: - -- **200** – Created -- **400** – Errors (invalid json, missing or invalid fields, etc) -- **401** – Unauthorized -- **412** – Precondition failed - -The **412** status code is used when a newer dashboard already exists (newer, its version is greater than the version that was sent). The -same status code is also used if another dashboard exists with the same title. The response body will look like this: - - HTTP/1.1 412 Precondition Failed - Content-Type: application/json; charset=UTF-8 - Content-Length: 97 - - { - "message": "The dashboard has been changed by someone else", - "status": "version-mismatch" - } - -In in case of title already exists the `status` property will be `name-exists`. - -### Get dashboard - -`GET /api/dashboards/db/:slug` - -Will return the dashboard given the dashboard slug. Slug is the url friendly version of the dashboard title. - -**Example Request**: - - GET /api/dashboards/db/production-overview HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - { - "meta": { - "isStarred": false, - "slug": "production-overview" - }, - "model": { - "id": null, - "title": "Production Overview", - "tags": [ "templated" ], - "timezone": "browser", - "rows": [ - { - } - ], - "schemaVersion": 6, - "version": 0 - } - } - -### Delete dashboard - -`DELETE /api/dashboards/db/:slug` - -The above will delete the dashboard with the specified slug. The slug is the url friendly (unique) version of the dashboard title. - -**Example Request**: - - DELETE /api/dashboards/db/test HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - {"title": "Test"} - -### Gets the home dashboard - -`GET /api/dashboards/home` - -Will return the home dashboard. - -**Example Request**: - - 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 - - { - "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 - } - } - -### Tags for Dashboard - - -`GET /api/dashboards/tags` - -Get all tabs of dashboards - -**Example Request**: - - 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 - - [ - { - "term":"tag1", - "count":1 - }, - { - "term":"tag2", - "count":4 - } - ] - -### Dashboard from JSON file - -`GET /file/:file` - -### Search Dashboards - -`GET /api/search/` - -Status Codes: - -- **query** – Search Query -- **tags** – Tags to use -- **starred** – Flag indicating if only starred Dashboards should be returned -- **tagcloud** - Flag indicating if a tagcloud should be returned - -**Example Request**: - - 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 - - [ - { - "id":1, - "title":"Production Overview", - "uri":"db/production-overview", - "type":"dash-db", - "tags":[], - "isStarred":false - } - ] - -## Data sources - -### Get all datasources - -`GET /api/datasources` - -**Example Request**: - - 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 - - [ - { - "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 - -`GET /api/datasources/:datasourceId` - -**Example Request**: - - 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 - - { - "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 - } - -### Create data source - -`POST /api/datasources` - -**Example Request**: - - 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 - } - - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - {"id":1,"message":"Datasource added"} - -### Update an existing data source - -`PUT /api/datasources/:datasourceId` - -**Example Request**: - - 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 - } - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - {"message":"Datasource updated"} - -### Delete an existing data source - -`DELETE /api/datasources/:datasourceId` - -**Example Request**: - - 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 - - {"message":"Data source deleted"} - -### Available data source types - -`GET /api/datasources/plugins` - -**Example Request**: - - GET /api/datasources/plugins HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - { - "grafana":{ - "metrics":true,"module":"plugins/datasource/grafana/datasource", - "name":"Grafana (for testing)", - "partials":{ - "query":"app/plugins/datasource/grafana/partials/query.editor.html" - }, - "pluginType":"datasource", - "serviceName":"GrafanaDatasource", - "type":"grafana" - } - } - -## Data source proxy calls - -`GET /api/datasources/proxy/:datasourceId/*` - -Proxies all calls to the actual datasource. - -## Organisation - -### Get current Organisation - -`GET /api/org` - -**Example Request**: - - 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 - - { - "id":1, - "name":"Main Org." - } - -### Get Organisation by Id - -`GET /api/orgs/:orgId` - -**Example Request**: - - 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":"" - } - } - -### 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 - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - { - "id":1, - "name":"Main Org.", - "address":{ - "address1":"", - "address2":"", - "city":"", - "zipCode":"", - "state":"", - "country":"" - } - } - -### Update current Organisation - -`PUT /api/org` - -**Example Request**: - - 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"} - - -### Get all users within the actual organisation - -`GET /api/org/users` - -**Example Request**: - - 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 - - [ - { - "orgId":1, - "userId":1, - "email":"admin@mygraf.com", - "login":"admin", - "role":"Admin" - } - ] - -### Add a new user to the actual organisation - -`POST /api/org/users` - -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" - } - - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - {"message":"User added to organization"} - -### Updates the given user - -`PATCH /api/org/users/:userId` - -**Example Request**: - - 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"} - - -### Delete user in actual organisation - -`DELETE /api/org/users/:userId` - -**Example Request**: - - 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"} - - -## Organisations - -### Search all Organisations - -`GET /api/orgs` - -**Example Request**: - - 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 - - [ - { - "id":1, - "name":"Main Org." - } - ] - -### Update Organisation - -`PUT /api/orgs/:orgId` - -Update Organisation, fields *Adress 1*, *Adress 2*, *City* are not implemented yet. - -**Example Request**: - - 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 - - {"message":"Organization updated"} - -### Get Users in Organisation - -`GET /api/orgs/:orgId/users` - -**Example Request**: - - 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" - } - ] - -### Add User in Organisation - -`POST /api/orgs/:orgId/users` - -**Example Request**: - - POST /api/orgs/1/users HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "loginOrEmail":"user", - "role":"Viewer" - } - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - {"message":"User added to organization"} - -### Update Users in Organisation - -`PATCH /api/orgs/:orgId/users/:userId` - -**Example Request**: - - PATCH /api/orgs/1/users/2 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "role":"Admin" - } - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - {"message":"Organization user updated"} - -### Delete User in Organisation - -`DELETE /api/orgs/:orgId/users/:userId` - -**Example Request**: - - 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 - - {"message":"User removed from organization"} - -## Users - -### Search Users - -`GET /api/users` - -**Example Request**: - - GET /api/users 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": "Admin", - "login": "admin", - "email": "admin@mygraf.com", - "isAdmin": true - }, - { - "id": 2, - "name": "User", - "login": "user", - "email": "user@mygraf.com", - "isAdmin": false - } - ] - -### Get single user by Id - -`GET /api/users/:id` - -**Example Request**: - - GET /api/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 - - { - "email": "user@mygraf.com" - "name": "admin", - "login": "admin", - "theme": "light", - "orgId": 1, - "isGrafanaAdmin": true - } - -### User Update - -`PUT /api/users/:id` - -**Example Request**: - - PUT /api/users/2 HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "email":"user@mygraf.com", - "name":"User2", - "login":"user", - "theme":"light" - } - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - {"message":"User updated"} - - -### Get Organisations for user - -`GET /api/users/:id/orgs` - -**Example Request**: - - GET /api/users/1/orgs 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, - "name":"Main Org.", - "role":"Admin" - } - ] - -## User - -### Actual User - -`GET /api/user` - -**Example Request**: - - 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 - - { - "email":"admin@mygraf.com", - "name":"Admin", - "login":"admin", - "theme":"light", - "orgId":1, - "isGrafanaAdmin":true - } - -### Change Password - -`PUT /api/user/password` - -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 - - { - "oldPassword": "old_password", - "newPassword": "new_password", - "confirmNew": "confirm_new_password" - } - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - {"message":"User password changed"} - -### Switch user context - -`POST /api/user/using/:organisationId` - -Switch user context to the given organisation. - -**Example Request**: - - 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 - - {"message":"Active organization changed"} - -### Organisations of the actual User - -`GET /api/user/orgs` - -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 - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - [ - { - "orgId":1, - "name":"Main Org.", - "role":"Admin" - } - ] - -### Star a dashboard - -`POST /api/user/stars/dashboard/:dashboardId` - -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 - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - {"message":"Dashboard starred!"} - -### Unstar a dashboard - -`DELETE /api/user/stars/dashboard/:dashboardId` - -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 - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - {"message":"Dashboard unstarred"} - - -## Snapshots - -### Create new snapshot - -`POST /api/snapshots` - -**Example Request**: - - POST /api/snapshots HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "dashboard": { - "editable":false, - "hideControls":true, - "nav":[ - { - "enable":false, - "type":"timepicker" - } - ], - "rows": [ - { - - } - ], - "style":"dark", - "tags":[], - "templating":{ - "list":[ - ] - }, - "time":{ - }, - "timezone":"browser", - "title":"Home", - "version":5 - }, - "expires": 3600 - } - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - { - "deleteKey":"XXXXXXX", - "deleteUrl":"myurl/dashboard/snapshot/XXXXXXX", - "key":"YYYYYYY", - "url":"myurl/dashboard/snapshot/YYYYYYY" - } - -Keys: - -- **deleteKey** – Key generated to delete the snapshot -- **key** – Key generated to share the dashboard - -### Get Snapshot by Id - -`GET /api/snapshots/:key` - -**Example Request**: - - 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 - - { - "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 - } - } - -### Delete Snapshot by Id - -`GET /api/snapshots-delete/:key` - -**Example Request**: - - 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 - - {"message":"Snapshot deleted. It might take an hour before it's cleared from a CDN cache."} - - -## Frontend Settings - -### Get Settings - -`GET /api/frontend/settings` - -**Example Request**: - - 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 - - { - "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 - -### Renew session based on remember cookie - -`GET /api/login/ping` - -**Example Request**: - - 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 - - {"message": "Logged in"} - -## Admin - -### Settings - -`GET /api/admin/settings` - -**Example Request**: - - GET /api/admin/settings - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - -**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", - "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", - "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` - -**Example Request**: - - GET /api/admin/stats - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - -**Example Response**: - - 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 - } - -### Global Users - -`POST /api/admin/users` - -Create new user - -**Example Request**: - - POST /api/admin/users HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - - { - "name":"User", - "email":"user@graf.com", - "login":"user", - "password":"userpassword" - } - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - {"id":5,"message":"User created"} - -### Password for User - -`PUT /api/admin/users/:id/password` - -Change password for specific user - -**Example Request**: - - PUT /api/admin/users/2/password HTTP/1.1 - Accept: application/json - Content-Type: application/json - Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk - -**Example Response**: - - HTTP/1.1 200 - Content-Type: application/json - - {"password":"userpassword"} - -### Permissions - -`PUT /api/admin/users/:id/permissions` - -**Example Request**: - - PUT /api/admin/users/2/permissions 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 permissions updated"} - -### Delete global User - -`DELETE /api/admin/users/:id` - -**Example Request**: - - DELETE /api/admin/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 - - {message: "User deleted"} From 616a6bec385e8306bce924a778ed379e990ee884 Mon Sep 17 00:00:00 2001 From: utkarshcmu Date: Fri, 5 Feb 2016 01:15:09 -0800 Subject: [PATCH 2/3] Added api heading in the main menu --- docs/mkdocs.yml | 10 +++++++++- docs/sources/http_api/first_steps.md | 14 ++++++-------- docs/sources/installation/migrating_to2.md | 2 +- 3 files changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e4c3dd91b79..843ba61a2f6 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -65,7 +65,6 @@ pages: - ['reference/plugins.md', 'Reference', 'Plugins'] - ['reference/export_import.md', 'Reference', 'Import & Export'] - ['reference/admin.md', 'Reference', 'Administration'] -- ['reference/http_api.md', 'Reference', 'HTTP API'] - ['reference/keyboard_shortcuts.md', 'Reference', 'Keyboard Shortcuts'] - ['datasources/overview.md', 'Data Sources', 'Overview'] @@ -77,6 +76,15 @@ pages: - ['datasources/kairosdb.md', 'Data Sources', 'KairosDB'] - ['datasources/prometheus.md', 'Data Sources', 'Prometheus'] +- ['http_api/first_steps.md', 'HTTP API', 'Authentication API'] +- ['http_api/dashboards.md', 'HTTP API', 'Dashboards API'] +- ['http_api/data_sources.md', 'HTTP API', 'Data Sources API'] +- ['http_api/orgs.md', 'HTTP API', 'Organisations API'] +- ['http_api/users.md', 'HTTP API', 'Users API'] +- ['http_api/admin.md', 'HTTP API', 'Admin API'] +- ['http_api/snapshots.md', 'HTTP API', 'Snapshots API'] +- ['http_api/general.md', 'HTTP API', 'Other API'] + - ['tutorials/index.md', 'Tutorials', 'Tutorials'] - ['tutorials/hubot_howto.md', 'Tutorials', 'How To integrate Hubot and Grafana'] diff --git a/docs/sources/http_api/first_steps.md b/docs/sources/http_api/first_steps.md index 0fbdf348327..2c63077a8f1 100644 --- a/docs/sources/http_api/first_steps.md +++ b/docs/sources/http_api/first_steps.md @@ -1,21 +1,19 @@ ---- -page_title: HTTP API +page_title: Authentication API page_description: Grafana HTTP API Reference page_keywords: grafana, admin, http, api, documentation --- -# HTTP API Reference +# Authentication API The Grafana backend exposes an HTTP API, the same API is used by the frontend to do everything from saving dashboards, creating users and updating data sources. -## Authorization - -### Tokens +## Tokens Currently you can authenticate via an `API Token` or via a `Session cookie` (acquired using regular login or oauth). -### Basic Auth +## Basic Auth If basic auth is enabled (it is enabled by default) you can authenticate your HTTP request via standard basic auth. @@ -26,7 +24,7 @@ curl example: {"id":1,"name":"Main Org."} ``` -### Create API Token +## Create API Token Open the sidemenu and click the organization dropdown and select the `API Keys` option. @@ -40,4 +38,4 @@ You use the token in all requests in the `Authorization` header, like this: Accept: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk -The `Authorization` header value should be `Bearer `. \ No newline at end of file +The `Authorization` header value should be `Bearer `. diff --git a/docs/sources/installation/migrating_to2.md b/docs/sources/installation/migrating_to2.md index 497b53e77e2..aebe4a83788 100644 --- a/docs/sources/installation/migrating_to2.md +++ b/docs/sources/installation/migrating_to2.md @@ -20,7 +20,7 @@ migrate to Grafana 2.0. ## Adding Data sources The `config.js` file has been deprecated. Data sources are now managed via -the UI or [HTTP API](../reference/http_api.md). Manage your +the UI or [HTTP API](../http_api/first_steps.md). Manage your organizations data sources by clicking on the `Data Sources` menu on the side menu (which can be toggled via the Grafana icon in the upper left of your browser). From 4ff6748eb448c6cf70c3e3d2fb5100a230dc0a96 Mon Sep 17 00:00:00 2001 From: utkarshcmu Date: Fri, 5 Feb 2016 01:47:34 -0800 Subject: [PATCH 3/3] Linked docs from main nav --- docs/mkdocs.yml | 17 +++++---- docs/sources/http_api/admin.md | 16 ++++---- .../http_api/{first_steps.md => auth.md} | 3 -- .../http_api/{dashboards.md => dashboard.md} | 22 +++++------ .../{data_sources.md => data_source.md} | 20 +++++----- docs/sources/http_api/{orgs.md => org.md} | 38 +++++++++---------- .../sources/http_api/{general.md => other.md} | 14 +++---- docs/sources/http_api/overview.md | 21 ++++++++++ .../http_api/{snapshots.md => snapshot.md} | 16 ++++---- docs/sources/http_api/{users.md => user.md} | 30 +++++++-------- docs/sources/installation/migrating_to2.md | 2 +- 11 files changed, 109 insertions(+), 90 deletions(-) rename docs/sources/http_api/{first_steps.md => auth.md} (86%) rename docs/sources/http_api/{dashboards.md => dashboard.md} (95%) rename docs/sources/http_api/{data_sources.md => data_source.md} (92%) rename docs/sources/http_api/{orgs.md => org.md} (90%) rename docs/sources/http_api/{general.md => other.md} (87%) create mode 100644 docs/sources/http_api/overview.md rename docs/sources/http_api/{snapshots.md => snapshot.md} (92%) rename docs/sources/http_api/{users.md => user.md} (91%) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 843ba61a2f6..7dc5922951b 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -76,14 +76,15 @@ pages: - ['datasources/kairosdb.md', 'Data Sources', 'KairosDB'] - ['datasources/prometheus.md', 'Data Sources', 'Prometheus'] -- ['http_api/first_steps.md', 'HTTP API', 'Authentication API'] -- ['http_api/dashboards.md', 'HTTP API', 'Dashboards API'] -- ['http_api/data_sources.md', 'HTTP API', 'Data Sources API'] -- ['http_api/orgs.md', 'HTTP API', 'Organisations API'] -- ['http_api/users.md', 'HTTP API', 'Users API'] -- ['http_api/admin.md', 'HTTP API', 'Admin API'] -- ['http_api/snapshots.md', 'HTTP API', 'Snapshots API'] -- ['http_api/general.md', 'HTTP API', 'Other API'] +- ['http_api/overview.md', 'API', 'Overview'] +- ['http_api/auth.md', 'API', 'Authentication API'] +- ['http_api/dashboard.md', 'API', 'Dashboard API'] +- ['http_api/data_source.md', 'API', 'Data Source API'] +- ['http_api/org.md', 'API', 'Organisation API'] +- ['http_api/user.md', 'API', 'User API'] +- ['http_api/admin.md', 'API', 'Admin API'] +- ['http_api/snapshot.md', 'API', 'Snapshot API'] +- ['http_api/other.md', 'API', 'Other API'] - ['tutorials/index.md', 'Tutorials', 'Tutorials'] - ['tutorials/hubot_howto.md', 'Tutorials', 'How To integrate Hubot and Grafana'] diff --git a/docs/sources/http_api/admin.md b/docs/sources/http_api/admin.md index 4688b4f5d9f..ba1a0923861 100644 --- a/docs/sources/http_api/admin.md +++ b/docs/sources/http_api/admin.md @@ -4,9 +4,9 @@ page_description: Grafana Admin API Reference page_keywords: grafana, admin, http, api, documentation --- -## Admin API +# Admin API -### Settings +## Settings `GET /api/admin/settings` @@ -162,7 +162,7 @@ page_keywords: grafana, admin, http, api, documentation } } -### Grafana Stats +## Grafana Stats `GET /api/admin/stats` @@ -190,7 +190,7 @@ page_keywords: grafana, admin, http, api, documentation "grafana_admin_count":2 } -### Global Users +## Global Users `POST /api/admin/users` @@ -217,7 +217,7 @@ Create new user {"id":5,"message":"User created"} -### Password for User +## Password for User `PUT /api/admin/users/:id/password` @@ -237,7 +237,7 @@ Change password for specific user {"password":"userpassword"} -### Permissions +## Permissions `PUT /api/admin/users/:id/permissions` @@ -255,7 +255,7 @@ Change password for specific user {message: "User permissions updated"} -### Delete global User +## Delete global User `DELETE /api/admin/users/:id` @@ -271,4 +271,4 @@ Change password for specific user HTTP/1.1 200 Content-Type: application/json - {message: "User deleted"} \ No newline at end of file + {message: "User deleted"} diff --git a/docs/sources/http_api/first_steps.md b/docs/sources/http_api/auth.md similarity index 86% rename from docs/sources/http_api/first_steps.md rename to docs/sources/http_api/auth.md index 2c63077a8f1..df874d1653e 100644 --- a/docs/sources/http_api/first_steps.md +++ b/docs/sources/http_api/auth.md @@ -6,9 +6,6 @@ page_keywords: grafana, admin, http, api, documentation # Authentication API -The Grafana backend exposes an HTTP API, the same API is used by the frontend to do everything from saving -dashboards, creating users and updating data sources. - ## Tokens Currently you can authenticate via an `API Token` or via a `Session cookie` (acquired using regular login or oauth). diff --git a/docs/sources/http_api/dashboards.md b/docs/sources/http_api/dashboard.md similarity index 95% rename from docs/sources/http_api/dashboards.md rename to docs/sources/http_api/dashboard.md index e1cbf6e436f..68f6ab022cc 100644 --- a/docs/sources/http_api/dashboards.md +++ b/docs/sources/http_api/dashboard.md @@ -1,12 +1,12 @@ ---- -page_title: Dashboards API -page_description: Grafana Dashboards API Reference -page_keywords: grafana, admin, http, api, documentation, dashboards +page_title: Dashboard API +page_description: Grafana Dashboard API Reference +page_keywords: grafana, admin, http, api, documentation, dashboard --- -## Dashboards API +# Dashboard API -### Create / Update dashboard +## Create / Update dashboard `POST /api/dashboards/db` @@ -73,7 +73,7 @@ same status code is also used if another dashboard exists with the same title. T In in case of title already exists the `status` property will be `name-exists`. -### Get dashboard +## Get dashboard `GET /api/dashboards/db/:slug` @@ -110,7 +110,7 @@ Will return the dashboard given the dashboard slug. Slug is the url friendly ver } } -### Delete dashboard +## Delete dashboard `DELETE /api/dashboards/db/:slug` @@ -130,7 +130,7 @@ The above will delete the dashboard with the specified slug. The slug is the url {"title": "Test"} -### Gets the home dashboard +## Gets the home dashboard `GET /api/dashboards/home` @@ -186,7 +186,7 @@ Will return the home dashboard. } } -### Tags for Dashboard +## Tags for Dashboard `GET /api/dashboards/tags` @@ -216,11 +216,11 @@ Get all tabs of dashboards } ] -### Dashboard from JSON file +## Dashboard from JSON file `GET /file/:file` -### Search Dashboards +## Search Dashboards `GET /api/search/` diff --git a/docs/sources/http_api/data_sources.md b/docs/sources/http_api/data_source.md similarity index 92% rename from docs/sources/http_api/data_sources.md rename to docs/sources/http_api/data_source.md index 8e2bc4e88de..57352161d31 100644 --- a/docs/sources/http_api/data_sources.md +++ b/docs/sources/http_api/data_source.md @@ -1,12 +1,12 @@ ---- -page_title: Data sources API -page_description: Grafana Data sources API Reference -page_keywords: grafana, admin, http, api, documentation, datasources +page_title: Data source API +page_description: Grafana Data source API Reference +page_keywords: grafana, admin, http, api, documentation, datasource --- -## Data sources API +# Data source API -### Get all datasources +## Get all datasources `GET /api/datasources` @@ -41,7 +41,7 @@ page_keywords: grafana, admin, http, api, documentation, datasources } ] -### Get a single data sources by Id +## Get a single data sources by Id `GET /api/datasources/:datasourceId` @@ -74,7 +74,7 @@ page_keywords: grafana, admin, http, api, documentation, datasources "jsonData":null } -### Create data source +## Create data source `POST /api/datasources` @@ -101,7 +101,7 @@ page_keywords: grafana, admin, http, api, documentation, datasources {"id":1,"message":"Datasource added"} -### Update an existing data source +## Update an existing data source `PUT /api/datasources/:datasourceId` @@ -136,7 +136,7 @@ page_keywords: grafana, admin, http, api, documentation, datasources {"message":"Datasource updated"} -### Delete an existing data source +## Delete an existing data source `DELETE /api/datasources/:datasourceId` @@ -154,7 +154,7 @@ page_keywords: grafana, admin, http, api, documentation, datasources {"message":"Data source deleted"} -### Available data source types +## Available data source types `GET /api/datasources/plugins` diff --git a/docs/sources/http_api/orgs.md b/docs/sources/http_api/org.md similarity index 90% rename from docs/sources/http_api/orgs.md rename to docs/sources/http_api/org.md index 9c378aaa06a..adb5d5cd31e 100644 --- a/docs/sources/http_api/orgs.md +++ b/docs/sources/http_api/org.md @@ -1,12 +1,12 @@ ---- -page_title: Organisations API -page_description: Grafana Organisations API Reference -page_keywords: grafana, admin, http, api, documentation, orgs, organisations +page_title: Organisation API +page_description: Grafana Organisation API Reference +page_keywords: grafana, admin, http, api, documentation, orgs, organisation --- -## Organisation API +# Organisation API -### Get current Organisation +## Get current Organisation `GET /api/org` @@ -27,7 +27,7 @@ page_keywords: grafana, admin, http, api, documentation, orgs, organisations "name":"Main Org." } -### Get Organisation by Id +## Get Organisation by Id `GET /api/orgs/:orgId` @@ -56,7 +56,7 @@ page_keywords: grafana, admin, http, api, documentation, orgs, organisations } } -### Get Organisation by Name +## Get Organisation by Name `GET /api/orgs/name/:orgName` @@ -85,7 +85,7 @@ page_keywords: grafana, admin, http, api, documentation, orgs, organisations } } -### Update current Organisation +## Update current Organisation `PUT /api/org` @@ -109,7 +109,7 @@ page_keywords: grafana, admin, http, api, documentation, orgs, organisations {"message":"Organization updated"} -### Get all users within the actual organisation +## Get all users within the actual organisation `GET /api/org/users` @@ -135,7 +135,7 @@ page_keywords: grafana, admin, http, api, documentation, orgs, organisations } ] -### Add a new user to the actual organisation +## Add a new user to the actual organisation `POST /api/org/users` @@ -161,7 +161,7 @@ Adds a global user to the actual organisation. {"message":"User added to organization"} -### Updates the given user +## Updates the given user `PATCH /api/org/users/:userId` @@ -185,7 +185,7 @@ Adds a global user to the actual organisation. {"message":"Organization user updated"} -### Delete user in actual organisation +## Delete user in actual organisation `DELETE /api/org/users/:userId` @@ -204,9 +204,9 @@ Adds a global user to the actual organisation. {"message":"User removed from organization"} -## Organisations +# Organisations -### Search all Organisations +## Search all Organisations `GET /api/orgs` @@ -229,7 +229,7 @@ Adds a global user to the actual organisation. } ] -### Update Organisation +## Update Organisation `PUT /api/orgs/:orgId` @@ -254,7 +254,7 @@ Update Organisation, fields *Adress 1*, *Adress 2*, *City* are not implemented y {"message":"Organization updated"} -### Get Users in Organisation +## Get Users in Organisation `GET /api/orgs/:orgId/users` @@ -279,7 +279,7 @@ Update Organisation, fields *Adress 1*, *Adress 2*, *City* are not implemented y } ] -### Add User in Organisation +## Add User in Organisation `POST /api/orgs/:orgId/users` @@ -302,7 +302,7 @@ Update Organisation, fields *Adress 1*, *Adress 2*, *City* are not implemented y {"message":"User added to organization"} -### Update Users in Organisation +## Update Users in Organisation `PATCH /api/orgs/:orgId/users/:userId` @@ -324,7 +324,7 @@ Update Organisation, fields *Adress 1*, *Adress 2*, *City* are not implemented y {"message":"Organization user updated"} -### Delete User in Organisation +## Delete User in Organisation `DELETE /api/orgs/:orgId/users/:userId` diff --git a/docs/sources/http_api/general.md b/docs/sources/http_api/other.md similarity index 87% rename from docs/sources/http_api/general.md rename to docs/sources/http_api/other.md index d110851d9dc..8852b6ccb38 100644 --- a/docs/sources/http_api/general.md +++ b/docs/sources/http_api/other.md @@ -1,12 +1,12 @@ ---- -page_title: General APIs -page_description: Grafana General API Reference +page_title: Other APIs +page_description: Grafana Other API Reference page_keywords: grafana, admin, http, api, documentation, dashboards --- -## Frontend Settings API +# Frontend Settings API -### Get Settings +## Get Settings `GET /api/frontend/settings` @@ -50,9 +50,9 @@ page_keywords: grafana, admin, http, api, documentation, dashboards "defaultDatasource": "Grafana" } -## Login API +# Login API -### Renew session based on remember cookie +## Renew session based on remember cookie `GET /api/login/ping` @@ -68,4 +68,4 @@ page_keywords: grafana, admin, http, api, documentation, dashboards HTTP/1.1 200 Content-Type: application/json - {"message": "Logged in"} \ No newline at end of file + {"message": "Logged in"} diff --git a/docs/sources/http_api/overview.md b/docs/sources/http_api/overview.md new file mode 100644 index 00000000000..8e7e2d60ad3 --- /dev/null +++ b/docs/sources/http_api/overview.md @@ -0,0 +1,21 @@ +---- +page_title: HTTP API +page_description: Grafana HTTP API Reference +page_keywords: grafana, admin, http, api, documentation +--- + +# HTTP API Reference + +The Grafana backend exposes an HTTP API, the same API is used by the frontend to do everything from saving +dashboards, creating users and updating data sources. + +###Supported HTTP APIs: + +* [Authentication API](/http_api/auth/) +* [Dashboard API](/http_api/dashboard/) +* [Data Source API](/http_api/data_source/) +* [Organisation API](/http_api/org/) +* [User API](/http_api/user/) +* [Admin API](/http_api/admin/) +* [Snapshot API](/http_api/snapshot/) +* [Other API](/http_api/other/) diff --git a/docs/sources/http_api/snapshots.md b/docs/sources/http_api/snapshot.md similarity index 92% rename from docs/sources/http_api/snapshots.md rename to docs/sources/http_api/snapshot.md index cbfc28cd71b..8f18c6ed81f 100644 --- a/docs/sources/http_api/snapshots.md +++ b/docs/sources/http_api/snapshot.md @@ -1,12 +1,12 @@ ---- -page_title: Snapshots API -page_description: Grafana Snapshots API Reference -page_keywords: grafana, admin, http, api, documentation, snapshots, dashboards +page_title: Snapshot API +page_description: Grafana Snapshot API Reference +page_keywords: grafana, admin, http, api, documentation, snapshot, dashboard --- -## Snapshots API +# Snapshot API -### Create new snapshot +## Create new snapshot `POST /api/snapshots` @@ -63,7 +63,7 @@ Keys: - **deleteKey** – Key generated to delete the snapshot - **key** – Key generated to share the dashboard -### Get Snapshot by Id +## Get Snapshot by Id `GET /api/snapshots/:key` @@ -118,7 +118,7 @@ Keys: } } -### Delete Snapshot by Id +## Delete Snapshot by Id `GET /api/snapshots-delete/:key` @@ -134,4 +134,4 @@ Keys: HTTP/1.1 200 Content-Type: application/json - {"message":"Snapshot deleted. It might take an hour before it's cleared from a CDN cache."} \ No newline at end of file + {"message":"Snapshot deleted. It might take an hour before it's cleared from a CDN cache."} diff --git a/docs/sources/http_api/users.md b/docs/sources/http_api/user.md similarity index 91% rename from docs/sources/http_api/users.md rename to docs/sources/http_api/user.md index 6b6015d3018..aa870031ca2 100644 --- a/docs/sources/http_api/users.md +++ b/docs/sources/http_api/user.md @@ -1,12 +1,12 @@ ---- -page_title: Users API -page_description: Grafana Users API Reference -page_keywords: grafana, admin, http, api, documentation, users +page_title: User API +page_description: Grafana User API Reference +page_keywords: grafana, admin, http, api, documentation, user --- -## Users API +# User API -### Search Users +## Search Users `GET /api/users` @@ -39,7 +39,7 @@ page_keywords: grafana, admin, http, api, documentation, users } ] -### Get single user by Id +## Get single user by Id `GET /api/users/:id` @@ -64,7 +64,7 @@ page_keywords: grafana, admin, http, api, documentation, users "isGrafanaAdmin": true } -### User Update +## User Update `PUT /api/users/:id` @@ -90,7 +90,7 @@ page_keywords: grafana, admin, http, api, documentation, users {"message":"User updated"} -### Get Organisations for user +## Get Organisations for user `GET /api/users/:id/orgs` @@ -116,7 +116,7 @@ page_keywords: grafana, admin, http, api, documentation, users ## User -### Actual User +## Actual User `GET /api/user` @@ -141,7 +141,7 @@ page_keywords: grafana, admin, http, api, documentation, users "isGrafanaAdmin":true } -### Change Password +## Change Password `PUT /api/user/password` @@ -167,7 +167,7 @@ Changes the password for the user {"message":"User password changed"} -### Switch user context +## Switch user context `POST /api/user/using/:organisationId` @@ -187,7 +187,7 @@ Switch user context to the given organisation. {"message":"Active organization changed"} -### Organisations of the actual User +## Organisations of the actual User `GET /api/user/orgs` @@ -213,7 +213,7 @@ Return a list of all organisations of the current user. } ] -### Star a dashboard +## Star a dashboard `POST /api/user/stars/dashboard/:dashboardId` @@ -233,7 +233,7 @@ Stars the given Dashboard for the actual user. {"message":"Dashboard starred!"} -### Unstar a dashboard +## Unstar a dashboard `DELETE /api/user/stars/dashboard/:dashboardId` @@ -251,4 +251,4 @@ Deletes the starring of the given Dashboard for the actual user. HTTP/1.1 200 Content-Type: application/json - {"message":"Dashboard unstarred"} \ No newline at end of file + {"message":"Dashboard unstarred"} diff --git a/docs/sources/installation/migrating_to2.md b/docs/sources/installation/migrating_to2.md index aebe4a83788..32e9c3371f3 100644 --- a/docs/sources/installation/migrating_to2.md +++ b/docs/sources/installation/migrating_to2.md @@ -20,7 +20,7 @@ migrate to Grafana 2.0. ## Adding Data sources The `config.js` file has been deprecated. Data sources are now managed via -the UI or [HTTP API](../http_api/first_steps.md). Manage your +the UI or [HTTP API](../http_api/overview.md). Manage your organizations data sources by clicking on the `Data Sources` menu on the side menu (which can be toggled via the Grafana icon in the upper left of your browser).