From 8377d3630c4c85e3dac0aaec94ab7fb9ebd752ae Mon Sep 17 00:00:00 2001 From: Daniel Lee Date: Thu, 15 Feb 2018 23:05:16 +0100 Subject: [PATCH] docs: team API. Closes #10832 --- .../sources/http_api/dashboard_permissions.md | 32 -- docs/sources/http_api/team.md | 306 ++++++++++++++++++ 2 files changed, 306 insertions(+), 32 deletions(-) create mode 100644 docs/sources/http_api/team.md diff --git a/docs/sources/http_api/dashboard_permissions.md b/docs/sources/http_api/dashboard_permissions.md index 3d54b4011d4..4b87dbf83c2 100644 --- a/docs/sources/http_api/dashboard_permissions.md +++ b/docs/sources/http_api/dashboard_permissions.md @@ -147,35 +147,3 @@ Status Codes: - **401** - Unauthorized - **403** - Access denied - **404** - Dashboard not found - - -## Delete permission for a dashboard or folder - -`DELETE /api/dashboards/id/:dashboardId/acl/:aclId` - -The above will delete a permission from a dashboard or folder given the permission id. - -**Example Request**: - -```http -DELETE /api/dashboards/id/1/acl/540 HTTP/1.1 -Accept: application/json -Content-Type: application/json -Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk -``` - -**Example Response**: - -```http -HTTP/1.1 200 -Content-Type: application/json -Content-Length: 0 -``` - -Status Codes: - -- **200** - Ok -- **401** - Unauthorized -- **403** - Access denied -- **404** - Dashboard permission not found - diff --git a/docs/sources/http_api/team.md b/docs/sources/http_api/team.md new file mode 100644 index 00000000000..1aed5fec395 --- /dev/null +++ b/docs/sources/http_api/team.md @@ -0,0 +1,306 @@ ++++ +title = "Team HTTP API " +description = "Grafana Team HTTP API" +keywords = ["grafana", "http", "documentation", "api", "team", "teams", "group"] +aliases = ["/http_api/team/"] +type = "docs" +[menu.docs] +name = "Teams" +parent = "http_api" ++++ + +# Team API + +This API can be used to create/update/delete Teams and to add/remove users to Teams. All actions require that the user has the Admin role for the organization. + +## Team Search With Paging + +`GET /api/teams/search?perpage=50&page=1&query=mytea` + +or + +`GET /api/teams/search?name=myteam` + +```http +GET /api/teams/search?perpage=10&page=1&query=myteam HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= +``` + +### Using the query parameter + +Default value for the `perpage` parameter is `1000` and for the `page` parameter is `1`. + +The `totalCount` field in the response can be used for pagination of the teams list E.g. if `totalCount` is equal to 100 teams and the `perpage` parameter is set to 10 then there are 10 pages of teams. + +The `query` parameter is optional and it will return results where the query value is contained in the `name` field. Query values with spaces need to be url encoded e.g. `query=my%20team`. + +### Using the name parameter + +The `name` parameter returns a single team if the parameter matches the `name` field. + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + + "totalCount": 1, + "teams": [ + { + "id": 1, + "orgId": 1, + "name": "MyTestTeam", + "email": "", + "avatarUrl": "\/avatar\/3f49c15916554246daa714b9bd0ee398", + "memberCount": 1 + } + ], + "page": 1, + "perPage": 1000 +} +``` + +Status Codes: + +- **200** - Ok +- **401** - Unauthorized +- **403** - Permission denied + +## Get Team By Id + +`GET /api/teams/:id` + +**Example Request**: + +```http +GET /api/teams/1 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= +``` + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +{ + "id": 1, + "orgId": 1, + "name": "MyTestTeam", + "email": "", + "created": "2017-12-15T10:40:45+01:00", + "updated": "2017-12-15T10:40:45+01:00" +} +``` + +Status Codes: + +- **200** - Ok +- **401** - Unauthorized +- **403** - Permission denied +- **404** - Team not found + +## Add Team + +The Team `name` needs to be unique. `name` is required and `email` is optional. + +`POST /api/teams` + +**Example Request**: + +```http +POST /api/teams HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= + +{ + "name": "MyTestTeam", + "email": "email@test.com" +} +``` + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +{"message":"Team created","teamId":2} +``` + +Status Codes: + +- **200** - Ok +- **401** - Unauthorized +- **403** - Permission denied +- **409** - Team name is taken + +## Update Team + +There are two fields that can be updated for a team: `name` and `email`. + +`PUT /api/teams/:id` + +**Example Request**: + +```http +PUT /api/teams/2 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= + +{ + "name": "MyTestTeam", + "email": "email@test.com" +} +``` + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +{"message":"Team updated"} +``` + +## Delete Team By Id + +`DELETE /api/teams/:id` + +**Example Request**: + +```http +DELETE /api/teams/2 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= +``` + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +{"message":"Team deleted"} +``` + +Status Codes: + +- **200** - Ok +- **401** - Unauthorized +- **403** - Permission denied +- **404** - Failed to delete Team. ID not found + +## Get Team Members + +`GET /api/teams/:teamId/members` + +**Example Request**: + +```http +GET /api/teams/1/members HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= +``` + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +[ + { + "orgId": 1, + "teamId": 1, + "userId": 3, + "email": "user1@email.com", + "login": "user1", + "avatarUrl": "\/avatar\/1b3c32f6386b0185c40d359cdc733a79" + }, + { + "orgId": 1, + "teamId": 1, + "userId": 2, + "email": "user2@email.com", + "login": "user2", + "avatarUrl": "\/avatar\/cad3c68da76e45d10269e8ef02f8e73e" + } +] +``` + +Status Codes: + +- **200** - Ok +- **401** - Unauthorized +- **403** - Permission denied + +## Add Team Member + +`POST /api/teams/:teamId/members` + +**Example Request**: + +```http +POST /api/teams/1/members HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= + +{ + "userId": 2 +} +``` + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +{"message":"Member added to Team"} +``` + +Status Codes: + +- **200** - Ok +- **400** - User is already added to this team +- **401** - Unauthorized +- **403** - Permission denied +- **500** - Failed to add Member to Team + +## Remove Member From Team + +`DELETE /api/teams/:teamId/members/:userId` + +**Example Request**: + +```http +DELETE /api/teams/2/members/3 HTTP/1.1 +Accept: application/json +Content-Type: application/json +Authorization: Basic YWRtaW46YWRtaW4= +``` + +**Example Response**: + +```http +HTTP/1.1 200 +Content-Type: application/json + +{"message":"Team Member removed"} +``` + +Status Codes: + +- **200** - Ok +- **401** - Unauthorized +- **403** - Permission denied