IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #2384 from sbengo/improved_http_api_doc

Browse Source 
Added docs to http_api
This commit is contained in:
Torkel Ödegaard 2015-07-23 09:43:02 +02:00
commit cd832ea77c
1 changed files with 780 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

826
docs/sources/reference/http_api.md
View File

@ -154,6 +154,20 @@ Will return the dashboard given the dashboard slug. Slug is the url friendly ver
The above will delete the dashboard with the specified slug. The slug is the url friendly (unique) version of the dashboard title. 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 ### Gets the home dashboard
`GET /api/dashboards/home` `GET /api/dashboards/home`
@ -173,41 +187,41 @@ Will return the home dashboard.
Content-Type: application/json Content-Type: application/json
{ {
"meta": { "meta": {
"isHome":true, "isHome":true,
"canSave":false, "canSave":false,
"canEdit":false, "canEdit":false,
"canStar":false, "canStar":false,
"slug":"", "slug":"",
"expires":"0001-01-01T00:00:00Z", "expires":"0001-01-01T00:00:00Z",
"created":"0001-01-01T00:00:00Z" "created":"0001-01-01T00:00:00Z"
}, },
"dashboard": { "dashboard": {
"editable":false, "editable":false,
"hideControls":true, "hideControls":true,
"nav":[ "nav":[
{
"enable":false,
"type":"timepicker"
}
],
"rows": [
{ {
"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
}
} }
### Tags for Dashboard ### Tags for Dashboard
@ -426,7 +440,7 @@ Status Codes:
HTTP/1.1 200 HTTP/1.1 200
Content-Type: application/json Content-Type: application/json
{"message":"Data source deleted"} {"message":"Data source deleted"}
### Available data source types ### Available data source types
@ -485,6 +499,29 @@ Proxies all calls to the actual datasource.
"id":1, "id":1,
"name":"Main Org." "name":"Main Org."
} }
### 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 all users within the actual organisation
@ -505,11 +542,11 @@ Proxies all calls to the actual datasource.
[ [
{ {
"orgId":1, "orgId":1,
"userId":1, "userId":1,
"email":"admin@mygraf.com", "email":"admin@mygraf.com",
"login":"admin", "login":"admin",
"role":"Admin" "role":"Admin"
} }
] ]
@ -588,57 +625,297 @@ Adds a global user to the actual organisation.
`GET /api/orgs` `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 ### Update Organisation
`PUT /api/orgs/:orgId` `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 Users in Organisation
`GET /api/orgs/:orgId/users` `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 ### Add User in Organisation
`POST /api/orgs/:orgId/users` `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 ### Update Users in Organisation
`PATCH /api/orgs/:orgId/users/:userId` `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 User in Organisation
`DELETE /api/orgs/:orgId/users/:userId` `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 ## Users
### Search Users ### Search Users
`GET /api/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 single user by Id
`GET /api/users/: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 ### User Update
`PUT /api/users/:id` `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 Organisations for user
`GET /api/users/:id/orgs` `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 ## 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 ### Change Password
`PUT /api/user/password` `PUT /api/user/password`
Changes the password for the user Changes the password for the user
### Actual User **Example Request**:
`GET /api/user` PUT /api/user/password HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
The above will return the current user. {
"password": ""new_password"
}
**Example Response**:
HTTP/1.1 200
Content-Type: application/json
{"message":"User password updated"}
### Switch user context ### Switch user context
@ -646,11 +923,45 @@ The above will return the current user.
Switch user context to the given organisation. 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 ### Organisations of the actual User
`GET /api/user/orgs` `GET /api/user/orgs`
The above will return a list of all organisations of the current user. 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 ### Star a dashboard
@ -658,11 +969,40 @@ The above will return a list of all organisations of the current user.
Stars the given Dashboard for the actual user. 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 ### Unstar a dashboard
`DELETE /api/user/stars/dashboard/:dashboardId` `DELETE /api/user/stars/dashboard/:dashboardId`
Deletes the staring of the given Dashboard for the actual user. 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 ## Snapshots
@ -670,13 +1010,133 @@ Deletes the staring of the given Dashboard for the actual user.
`POST /api/snapshots` `POST /api/snapshots`
### Get Snapshot by Id **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` `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 ### Delete Snapshot by Id
`DELETE /api/snapshots-delete/:key` `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 ## Frontend Settings
@ -684,30 +1144,304 @@ Deletes the staring of the given Dashboard for the actual user.
`GET /api/frontend/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 ## Login
### Renew session based on remember cookie ### Renew session based on remember cookie
`GET /api/login/ping` `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 ## Admin
### Settings ### Settings
`GET /api/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"
}
}
### Global Users ### Global Users
`POST /api/admin/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
{"message":"User created"}
### Password for User ### Password for User
`PUT /api/admin/users/:id/password` `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 ### Permissions
`PUT /api/admin/users/:id/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 global User
`DELETE /api/admin/users/:id` `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"}