From b5e96f5ec2d14abeab6d5839d0ca6ab94ea73700 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Wed, 21 Feb 2018 13:09:01 +0100 Subject: [PATCH 1/3] docs: folder http api --- docs/sources/http_api/folder.md | 337 ++++++++++++++++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 docs/sources/http_api/folder.md diff --git a/docs/sources/http_api/folder.md b/docs/sources/http_api/folder.md new file mode 100644 index 00000000000..13de0aab6c2 --- /dev/null +++ b/docs/sources/http_api/folder.md @@ -0,0 +1,337 @@ ++++ +title = "Folder HTTP API " +description = "Grafana Folder HTTP API" +keywords = ["grafana", "http", "documentation", "api", "folder"] +aliases = ["/http_api/folder/"] +type = "docs" +[menu.docs] +name = "Folder" +parent = "http_api" ++++ + +# Folder API + +## Identifier (id) vs unique identifier (uid) + +The identifier (id) of a folder is an auto-incrementing numeric value and is only unique per Grafana install. + +The unique identifier (uid) of a folder can be used for uniquely identify folders between multiple Grafana installs. It's automatically generated if not provided when creating a folder. The uid allows having consistent URL's for accessing folders and when syncing folders between multiple Grafana installs. This means that changing the title of a folder will not break any bookmarked links to that folder. + +The uid can have a maximum length of 40 characters. + + +## Get all folders + +`GET /api/folders` + +Returns all folders that the authenticated user has permission to view. + +**Example Request**: + +```http +GET /api/folders?limit=10 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +[ + { + "id":1, + "uid": "nErXDvCkzz", + "title": "Departmenet ABC", + "url": "/dashboards/f/nErXDvCkzz/department-abc", + "hasAcl": false, + "canSave": true, + "canEdit": true, + "canAdmin": true, + "createdBy": "admin", + "created": "2018-01-31T17:43:12+01:00", + "updatedBy": "admin", + "updated": "2018-01-31T17:43:12+01:00", + "version": 1 + } +] +``` + +## Get folder by uid + +`GET /api/folders/:uid` + +Will return the folder given the folder uid. + +**Example Request**: + +```http +GET /api/folders/nErXDvCkzzh HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +{ + "id":1, + "uid": "nErXDvCkzz", + "title": "Departmenet ABC", + "url": "/dashboards/f/nErXDvCkzz/department-abc", + "hasAcl": false, + "canSave": true, + "canEdit": true, + "canAdmin": true, + "createdBy": "admin", + "created": "2018-01-31T17:43:12+01:00", + "updatedBy": "admin", + "updated": "2018-01-31T17:43:12+01:00", + "version": 1 +} +``` + +Status Codes: + +- **200** – Found +- **401** – Unauthorized +- **403** – Access Denied +- **404** – Folder not found + +## Create folder + +`POST /api/folders` + +Creates a new folder. + +**Example Request**: + +```http +POST /api/folders HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +{ + "uid": "nErXDvCkzz", + "title": "Department ABC" +} +``` + +JSON Body schema: + +- **uid** – Optional [unique identifier](/http_api/folder/#identifier-id-vs-unique-identifier-uid). +- **title** – The title of the folder. + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +{ + "id":1, + "uid": "nErXDvCkzz", + "title": "Departmenet ABC", + "url": "/dashboards/f/nErXDvCkzz/department-abc", + "hasAcl": false, + "canSave": true, + "canEdit": true, + "canAdmin": true, + "createdBy": "admin", + "created": "2018-01-31T17:43:12+01:00", + "updatedBy": "admin", + "updated": "2018-01-31T17:43:12+01:00", + "version": 1 +} +``` + +Status Codes: + +- **200** – Created +- **400** – Errors (invalid json, missing or invalid fields, etc) +- **401** – Unauthorized +- **403** – Access Denied +- **412** – Precondition failed + +The **412** status code is used for explaing that you cannot create the folder and why. +There can be different reasons for this: + +- A folder or dashboard in the general folder with the same name already exists, `status=name-exists` +- A folder/dashboard with the same uid already exists, `status=uid-exists` + + The response body will have the following properties: + +```http +HTTP/1.1 412 Precondition Failed +Content-Type: application/json; charset=UTF-8 +Content-Length: 97 + +{ + "message": "A folder or dashboard in the general folder with the same name already exists", + "status": "name-exists" +} +``` + +## Update folder + +`PUT /api/folders/:uid` + +Updates an existing folder identified by uid. + +**Example Request**: + +```http +PUT /api/folders/nErXDvCkzz HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +{ + "title":"Department DEF", + "version": 1 +} +``` + +JSON Body schema: + +- **title** – The title of the folder. +- **version** – Provide the current version to be able to update the folder. Not needed if `overwrite=true`. +- **overwrite** – Set to true if you want to overwrite existing folder with newer version. + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +{ + "id":1, + "uid": "nErXDvCkzz", + "title": "Departmenet DEF", + "url": "/dashboards/f/nErXDvCkzz/department-def", + "hasAcl": false, + "canSave": true, + "canEdit": true, + "canAdmin": true, + "createdBy": "admin", + "created": "2018-01-31T17:43:12+01:00", + "updatedBy": "admin", + "updated": "2018-01-31T17:43:12+01:00", + "version": 1 +} +``` + +Status Codes: + +- **200** – Updated +- **400** – Errors (invalid json, missing or invalid fields, etc) +- **401** – Unauthorized +- **403** – Access Denied +- **404** – Folder not found +- **412** – Precondition failed + +The **412** status code is used for explaing that you cannot update the folder and why. +There can be different reasons for this: + +- A folder or dashboard in the general folder with the same name already exists, `status=name-exists` +- The folder has been changed by someone else, `status=version-mismatch` + + The response body will have the following properties: + +```http +HTTP/1.1 412 Precondition Failed +Content-Type: application/json; charset=UTF-8 +Content-Length: 97 + +{ + "message": "The folder has been changed by someone else", + "status": "version-mismatch" +} +``` + +## Delete folder + +`DELETE /api/folders/:uid` + +Deletes an existing folder identified by uid together with all dashboards stored in the folder, if any. This operation cannot be reverted. + +**Example Request**: + +```http +DELETE /api/folders/nErXDvCkzz HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + +``` + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +{ + "message":"Folder deleted" +} +``` + +Status Codes: + +- **200** – Deleted +- **401** – Unauthorized +- **403** – Access Denied +- **404** – Folder not found + +## Get folder by id + +`GET /api/folders/:id` + +Will return the folder identified by id. + +**Example Request**: + +```http +GET /api/folders/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +{ + "id":1, + "uid": "nErXDvCkzz", + "title": "Departmenet ABC", + "url": "/dashboards/f/nErXDvCkzz/department-abc", + "hasAcl": false, + "canSave": true, + "canEdit": true, + "canAdmin": true, + "createdBy": "admin", + "created": "2018-01-31T17:43:12+01:00", + "updatedBy": "admin", + "updated": "2018-01-31T17:43:12+01:00", + "version": 1 +} +``` + +Status Codes: + +- **200** – Found +- **401** – Unauthorized +- **403** – Access Denied +- **404** – Folder not found From 7d89f19f6fafe0a171b81d994867796007ace1a4 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Wed, 21 Feb 2018 13:09:54 +0100 Subject: [PATCH 2/3] docs: dashboard and folder permissions http api --- .../sources/http_api/dashboard_permissions.md | 22 +-- docs/sources/http_api/folder_permissions.md | 149 ++++++++++++++++++ 2 files changed, 160 insertions(+), 11 deletions(-) create mode 100644 docs/sources/http_api/folder_permissions.md diff --git a/docs/sources/http_api/dashboard_permissions.md b/docs/sources/http_api/dashboard_permissions.md index 4b87dbf83c2..26aa1550d7c 100644 --- a/docs/sources/http_api/dashboard_permissions.md +++ b/docs/sources/http_api/dashboard_permissions.md @@ -11,7 +11,7 @@ parent = "http_api" # Dashboard Permissions API -This API can be used to update/get the permissions for a dashboard or a folder. +This API can be used to update/get the permissions for a dashboard. Permissions with `dashboardId=-1` are the default permissions for users with the Viewer and Editor roles. Permissions can be set for a user, a team or a role (Viewer or Editor). Permissions cannot be set for Admins - they always have access to everything. @@ -21,16 +21,16 @@ The permission levels for the permission field: - 2 = Edit - 4 = Admin -## Get permissions for a dashboard or folder +## Get permissions for a dashboard -`GET /api/dashboards/id/:dashboardId/acl` +`GET /api/dashboards/id/:dashboardId/permissions` -Gets all existing permissions for the dashboard or folder with the given `dashboardId`. +Gets all existing permissions for the dashboard with the given `dashboardId`. **Example request**: ```http -GET /api/dashboards/id/1/acl HTTP/1.1 +GET /api/dashboards/id/1/permissions HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk @@ -90,18 +90,18 @@ Status Codes: - **200** - Ok - **401** - Unauthorized - **403** - Access denied -- **404** - Dashboard/folder not found +- **404** - Dashboard not found -## Update permissions for a dashboard or folder +## Update permissions for a dashboard -`POST /api/dashboards/id/:dashboardId/acl` +`POST /api/dashboards/id/:dashboardId/permissions` -Updates permissions for a dashboard or folder. This operation will remove existing permissions if they're not included in the request. +Updates permissions for a dashboard. This operation will remove existing permissions if they're not included in the request. **Example request**: ```http -POST /api/dashboards/id/1/acl +POST /api/dashboards/id/1/permissions Accept: application/json Content-Type: application/json Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk @@ -138,7 +138,7 @@ HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Content-Length: 35 -{"message":"Dashboard acl updated"} +{"message":"Dashboard permissions updated"} ``` Status Codes: diff --git a/docs/sources/http_api/folder_permissions.md b/docs/sources/http_api/folder_permissions.md new file mode 100644 index 00000000000..284ab70866f --- /dev/null +++ b/docs/sources/http_api/folder_permissions.md @@ -0,0 +1,149 @@ ++++ +title = "Folder Permissions HTTP API " +description = "Grafana Folder Permissions HTTP API" +keywords = ["grafana", "http", "documentation", "api", "folder", "permission", "permissions", "acl"] +aliases = ["/http_api/dashboardpermissions/"] +type = "docs" +[menu.docs] +name = "Folder Permissions" +parent = "http_api" ++++ + +# Folder Permissions API + +This API can be used to update/get the permissions for a folder. + +Permissions with `folderId=-1` are the default permissions for users with the Viewer and Editor roles. Permissions can be set for a user, a team or a role (Viewer or Editor). Permissions cannot be set for Admins - they always have access to everything. + +The permission levels for the permission field: + +- 1 = View +- 2 = Edit +- 4 = Admin + +## Get permissions for a folder + +`GET /api/folders/:uid/permissions` + +Gets all existing permissions for the folder with the given `uid`. + +**Example request**: + +```http +GET /api/folders/nErXDvCkzz/permissions HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk +``` + +**Example Response** + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 +Content-Length: 551 + +[ + { + "id": 1, + "folderId": -1, + "created": "2017-06-20T02:00:00+02:00", + "updated": "2017-06-20T02:00:00+02:00", + "userId": 0, + "userLogin": "", + "userEmail": "", + "teamId": 0, + "team": "", + "role": "Viewer", + "permission": 1, + "permissionName": "View", + "uid": "nErXDvCkzz", + "title": "", + "slug": "", + "isFolder": false, + "url": "" + }, + { + "id": 2, + "dashboardId": -1, + "created": "2017-06-20T02:00:00+02:00", + "updated": "2017-06-20T02:00:00+02:00", + "userId": 0, + "userLogin": "", + "userEmail": "", + "teamId": 0, + "team": "", + "role": "Editor", + "permission": 2, + "permissionName": "Edit", + "uid": "", + "title": "", + "slug": "", + "isFolder": false, + "url": "" + } +] +``` + +Status Codes: + +- **200** - Ok +- **401** - Unauthorized +- **403** - Access denied +- **404** - Folder not found + +## Update permissions for a folder + +`POST /api/folders/:uid/permissions` + +Updates permissions for a folder. This operation will remove existing permissions if they're not included in the request. + +**Example request**: + +```http +POST /api/folders/nErXDvCkzz/permissions +Accept: application/json +Content-Type: application/json +Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk + + "items": [ + { + "role": "Viewer", + "permission": 1 + }, + { + "role": "Editor", + "permission": 2 + }, + { + "teamId": 1, + "permission": 1 + }, + { + "userId": 11, + "permission": 4 + } + ] +} +``` + +JSON body schema: + +- **items** - The permission items to add/update. Items that are omitted from the list will be removed. + +**Example response**: + +```http +HTTP/1.1 200 OK +Content-Type: application/json; charset=UTF-8 +Content-Length: 35 + +{"message":"Folder permissions updated"} +``` + +Status Codes: + +- **200** - Ok +- **401** - Unauthorized +- **403** - Access denied +- **404** - Dashboard not found From 02b412b127ec6ca0890fddae4dad2af45bfe83d3 Mon Sep 17 00:00:00 2001 From: Marcus Efraimsson Date: Wed, 21 Feb 2018 13:11:32 +0100 Subject: [PATCH 3/3] docs: update http api index --- docs/sources/http_api/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/sources/http_api/index.md b/docs/sources/http_api/index.md index b00deaf6715..81b3c907c7a 100644 --- a/docs/sources/http_api/index.md +++ b/docs/sources/http_api/index.md @@ -21,6 +21,9 @@ dashboards, creating users and updating data sources. * [Authentication API]({{< relref "/http_api/auth.md" >}}) * [Dashboard API]({{< relref "/http_api/dashboard.md" >}}) * [Dashboard Versions API]({{< relref "http_api/dashboard_versions.md" >}}) +* [Dashboard Permissions API]({{< relref "http_api/dashboard_permissions.md" >}}) +* [Folder API]({{< relref "/http_api/folder.md" >}}) +* [Folder Permissions API]({{< relref "http_api/folder_permissions.md" >}}) * [Folder/dashboard search API]({{< relref "/http_api/folder_dashboard_search.md" >}}) * [Data Source API]({{< relref "http_api/data_source.md" >}}) * [Organisation API]({{< relref "http_api/org.md" >}})