From ceed42b6694b6054735b0b9f906a8c15cf9772f6 Mon Sep 17 00:00:00 2001 From: Sunbrye Ly Date: Thu, 8 Sep 2022 12:36:19 -0700 Subject: [PATCH 1/5] feat: release api docs updates --- api-docs/cloud/ref.yml | 594 +++++++++++++++++++++++++++++++++++++--- api-docs/v2.4/ref.yml | 595 ++++++++++++++++++++++++++++++++++++++--- 2 files changed, 1129 insertions(+), 60 deletions(-) diff --git a/api-docs/cloud/ref.yml b/api-docs/cloud/ref.yml index d95844326..04d9273b2 100644 --- a/api-docs/cloud/ref.yml +++ b/api-docs/cloud/ref.yml @@ -3469,12 +3469,16 @@ components: $ref: '#/components/schemas/PatchRetentionRules' type: object PatchOrganizationRequest: + description: | + An object that contains updated organization properties to apply. properties: description: - description: New description to set on the organization + description: | + The description of the organization. type: string name: - description: New name to set on the organization + description: | + The name of the organization. type: string type: object PatchRetentionRule: @@ -3688,8 +3692,12 @@ components: PostOrganizationRequest: properties: description: + description: | + The description of the organization. type: string name: + description: | + The name of the organization. type: string required: - name @@ -10920,6 +10928,27 @@ paths: '200': content: application/json: + examples: + successResponse: + value: + links: + self: /api/v2/orgs + orgs: + - createdAt: '2022-07-17T23:00:30.778487Z' + description: Example InfluxDB organization + id: INFLUX_ORG_ID + links: + buckets: /api/v2/buckets?org=INFLUX_ORG + dashboards: /api/v2/dashboards?org=INFLUX_ORG + labels: /api/v2/orgs/INFLUX_ORG_ID/labels + logs: /api/v2/orgs/INFLUX_ORG_ID/logs + members: /api/v2/orgs/INFLUX_ORG_ID/members + owners: /api/v2/orgs/INFLUX_ORG_ID/owners + secrets: /api/v2/orgs/INFLUX_ORG_ID/secrets + self: /api/v2/orgs/INFLUX_ORG_ID + tasks: /api/v2/tasks?org=InfluxData + name: INFLUX_ORG + updatedAt: '2022-07-17T23:00:30.778487Z' schema: $ref: '#/components/schemas/Organizations' description: Success. The response body contains a list of organizations. @@ -10938,12 +10967,23 @@ paths: - Organizations - Security and access endpoints post: - description: | - Creates an organization and returns the newly created organization. + description: > + Creates an + [organization](/influxdb/cloud/reference/glossary/#organization) + + and returns the newly created organization. + #### InfluxDB Cloud + - Doesn't allow you to use this endpoint to create organizations. + + + #### Related guides + + + - [Manage organizations](/influxdb/cloud/organizations) operationId: PostOrgs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -10958,13 +10998,35 @@ paths: '201': content: application/json: + examples: + successResponse: + value: + createdAt: '2022-08-24T23:05:52.881317Z' + description: '' + id: INFLUX_ORG_ID + links: + buckets: /api/v2/buckets?org=INFLUX_ORG + dashboards: /api/v2/dashboards?org=INFLUX_ORG + labels: /api/v2/orgs/INFLUX_ORG_ID/labels + logs: /api/v2/orgs/INFLUX_ORG_ID/logs + members: /api/v2/orgs/INFLUX_ORG_ID/members + owners: /api/v2/orgs/INFLUX_ORG_ID/owners + secrets: /api/v2/orgs/INFLUX_ORG_ID/secrets + self: /api/v2/orgs/INFLUX_ORG_ID + tasks: /api/v2/tasks?org=INFLUX_ORG + name: INFLUX_ORG + updatedAt: '2022-08-24T23:05:52.881318Z' schema: $ref: '#/components/schemas/Organization' - description: | - Success. The organization is created. - The response body contains the new organization. + description: Created. The response body contains the organization information. '400': $ref: '#/components/responses/BadRequestError' + examples: + invalidRequest: + summary: The `name` field is missing from the request body. + value: + code: invalid + message: org name is empty '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -10972,16 +11034,59 @@ paths: '500': $ref: '#/components/responses/InternalServerError' default: - $ref: '#/components/responses/GeneralServerError' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error summary: Create an organization tags: - Organizations + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST "http://localhost:8086/api/v2/orgs \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "INFLUX_ORG", + "description: "Example InfluxDB organization" + }' /api/v2/orgs/{orgID}: delete: + description: | + Deletes an organization. + + Deleting an organization from InfluxDB Cloud can't be undone. + Once deleted, all data associated with the organization is removed. + + #### InfluxDB Cloud + + - Does the following when you send a delete request: + + 1. Validates the request and queues the delete. + 2. Returns an HTTP `204` status code if queued; _error_ otherwise. + 3. Handles the delete asynchronously. + + #### InfluxDB OSS + + - Validates the request, handles the delete synchronously, + and then responds with success or failure. + + #### Limitations + + - Only one organization can be deleted per request. + + #### Related guides + + - [Delete organization](/influxdb/cloud/organizations/delete-orgs/) operationId: DeleteOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the organization to delete. + - description: | + The ID of the organization to delete. in: path name: orgID required: true @@ -10989,13 +11094,35 @@ paths: type: string responses: '204': - description: Delete has been accepted + description: | + Success. + + #### InfluxDB Cloud + - The organization is queued for deletion. + + #### InfluxDB OSS + - The organization is deleted. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' '404': content: application/json: + examples: + notFound: + summary: | + The requested organization was not found. + value: + code: not found + message: org not found schema: $ref: '#/components/schemas/Error' - description: Organization not found + description: | + Not found. + InfluxDB can't find the organization. + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -11006,10 +11133,19 @@ paths: tags: - Organizations get: + description: | + Retrieves an organization. + + Use this endpoint to retrieve information for a specific organization. + + #### Related guides + + - [View organization](/influxdb/cloud/organizations/view-orgs/) operationId: GetOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the organization to get. + - description: | + The ID of the organization to retrieve. in: path name: orgID required: true @@ -11021,7 +11157,28 @@ paths: application/json: schema: $ref: '#/components/schemas/Organization' - description: Organization details + description: | + Success. + The response body contains the organization information. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested organization wasn't found. + value: + code: not found + message: organization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + Organization not found. + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -11033,10 +11190,46 @@ paths: - Organizations - Security and access endpoints patch: + description: > + Updates an organization. + + + Use this endpoint to update properties + + (`name`, `description`) of an organization. + + + Updating an organization’s name affects all resources that reference the + + organization by name, including the following: + + + - Queries + + - Dashboards + + - Tasks + + - Telegraf configurations + + - Templates + + + If you change an organization name, be sure to update the organization + name + + in these resources as well. + + + #### Related Guides + + + - [Update an organization](/influxdb/cloud/organizations/update-org/) operationId: PatchOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the organization to get. + - description: | + The ID of the organization to update. in: path name: orgID required: true @@ -11047,7 +11240,7 @@ paths: application/json: schema: $ref: '#/components/schemas/PatchOrganizationRequest' - description: Organization update to apply + description: The organization update to apply. required: true responses: '200': @@ -11055,7 +11248,15 @@ paths: application/json: schema: $ref: '#/components/schemas/Organization' - description: Organization updated + description: Success. The response body contains the updated organization. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -11096,10 +11297,57 @@ paths: - Limits /api/v2/orgs/{orgID}/members: get: + description: > + Retrieves a list of all users that belong to an organization. + + + InfluxDB [users](/influxdb/cloud/reference/glossary/#user) have + + permission to access InfluxDB. + + + [Members](/influxdb/cloud/reference/glossary/#member) are users + + within the organization. + + + #### InfluxDB Cloud + + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + + - Member permissions are separate from API token permissions. + + - Member permissions are used in the context of the InfluxDB UI. + + + #### Required permissions + + + - `read-orgs INFLUX_ORG_ID` + + + `INFLUX_ORG_ID` is the ID of the organization that you retrieve a list + of + + members from. + + + #### Related guides + + + - [Manage users](/influxdb/cloud/users/) + + - [Manage members](/influxdb/cloud/organizations/members/) operationId: GetOrgsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. + - description: | + The ID of the organization to retrieve users for. in: path name: orgID required: true @@ -11109,15 +11357,52 @@ paths: '200': content: application/json: + examples: + successResponse: + value: + links: + self: /api/v2/orgs/055aa4783aa38398/members + users: + - id: 791df274afd48a83 + links: + self: /api/v2/users/791df274afd48a83 + name: example_user_1 + role: member + status: active + - id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_2 + role: owner + status: active schema: $ref: '#/components/schemas/ResourceMembers' - description: A list of organization members + description: > + Success. + + The response body contains a list of all users within the + organization. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' '404': content: application/json: + examples: + notFound: + summary: | + The requested organization wasn't found. + value: + code: not found + message: 404 page not found schema: $ref: '#/components/schemas/Error' - description: Organization not found + description: | + Not found. + InfluxDB can't find the organization. + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -11129,10 +11414,54 @@ paths: - Organizations - Security and access endpoints post: + description: > + Add a user to an organization. + + + InfluxDB [users](/influxdb/cloud/reference/glossary/#user) have + + permission to access InfluxDB. + + + [Members](/influxdb/cloud/reference/glossary/#member) are users + + within the organization. + + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + + - Member permissions are separate from API token permissions. + + - Member permissions are used in the context of the InfluxDB UI. + + + #### Required permissions + + + - `write-orgs INFLUX_ORG_ID` + + + `INFLUX_ORG_ID` is the ID of the organization that you want add a member + to. + + + #### Related guides + + + - [Manage users](/influxdb/cloud/users/) + + - [Manage members](/influxdb/cloud/organizations/members/) operationId: PostOrgsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. + - description: | + The ID of the organization. in: path name: orgID required: true @@ -11143,15 +11472,41 @@ paths: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member + description: | + The user to add to the organization. required: true responses: '201': content: application/json: + examples: + successResponse: + value: + id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_1 + role: member + status: active schema: $ref: '#/components/schemas/ResourceMember' - description: Added to organization created + description: | + Success. + The response body contains the user information. + '400': + $ref: '#/components/responses/BadRequestError' + examples: + invalidRequest: + summary: The user `id` is missing from the request body. + value: + code: invalid + message: user id missing or invalid + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -11161,18 +11516,69 @@ paths: summary: Add a member to an organization tags: - Organizations + x-codeSamples: + - label: cURL + lang: Shell + source: > + curl --request POST + "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/members \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "id": "09cfb87051cbe000" + }' /api/v2/orgs/{orgID}/members/{userID}: delete: + description: > + Removes a member from an organization. + + + Use this endpoint to remove a user's member privileges from a bucket. + This + + removes the user's `read` and `write` permissions from the organization. + + + #### InfluxDB Cloud + + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + + - Member permissions are separate from API token permissions. + + - Member permissions are used in the context of the InfluxDB UI. + + + #### Required permissions + + + - `write-orgs INFLUX_ORG_ID` + + + `INFLUX_ORG_ID` is the ID of the organization that you want to remove an + + owner from. + + + #### Related guides + + + - [Manage members](/influxdb/cloud/organizations/members/) operationId: DeleteOrgsIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. + - description: The ID of the user to remove. in: path name: userID required: true schema: type: string - - description: The organization ID. + - description: The ID of the organization to remove a user from. in: path name: orgID required: true @@ -11180,7 +11586,15 @@ paths: type: string responses: '204': - description: Member removed + description: | + Success. + The user is no longer a member of the organization. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -11193,8 +11607,26 @@ paths: - Security and access endpoints /api/v2/orgs/{orgID}/owners: get: - description: | + description: > Retrieves a list of all owners of an organization. + + + #### InfluxDB Cloud + + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Required permissions + + + - `read-orgs INFLUX_ORG_ID` + + + `INFLUX_ORG_ID` is the ID of the organization that you want to retrieve + a + + list of owners from. operationId: GetOrgsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11209,6 +11641,18 @@ paths: '200': content: application/json: + examples: + successResponse: + value: + links: + self: /api/v2/orgs/055aa4783aa38398/owners + users: + - id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_2 + role: owner + status: active schema: $ref: '#/components/schemas/ResourceOwners' description: A list of organization owners @@ -11268,6 +11712,15 @@ paths: requestBody: content: application/json: + examples: + successResponse: + value: + id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_1 + role: owner + status: active schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' description: The user to add as an owner of the organization. @@ -11281,6 +11734,14 @@ paths: description: | Success. The user is an owner of the organization. The response body contains the owner with role and user detail. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -11290,18 +11751,71 @@ paths: summary: Add an owner to an organization tags: - Organizations + x-codeSamples: + - label: cURL + lang: Shell + source: > + curl --request POST + "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/owners \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "id": "09cfb87051cbe000" + }' /api/v2/orgs/{orgID}/owners/{userID}: delete: + description: > + Removes an [owner](/influxdb/cloud/reference/glossary/#owner) from + + the organization. + + + Organization owners have permission to delete organizations and remove + user and member + + permissions from the organization. + + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + + - Owner permissions are separate from API token permissions. + + - Owner permissions are used in the context of the InfluxDB UI. + + + #### Required permissions + + + - `write-orgs INFLUX_ORG_ID` + + + `INFLUX_ORG_ID` is the ID of the organization that you want remove an + owner + + from. + + + #### Related endpoints + + - [Authorizations](#tag/Authorizations) operationId: DeleteOrgsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. + - description: The ID of the user to remove. in: path name: userID required: true schema: type: string - - description: The organization ID. + - description: | + The ID of the organization to remove an owner from. in: path name: orgID required: true @@ -11309,7 +11823,15 @@ paths: type: string responses: '204': - description: Owner removed + description: | + Success. + The user is no longer an owner of the organization. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -18138,7 +18660,19 @@ tags: - name: Limits - name: NotificationEndpoints - name: NotificationRules - - name: Organizations + - description: > + Manage your + [organization](/influxdb/cloud/reference/glossary/#organization). + + An organization is a workspace for a group of users. Organizations can be + + used to separate different environments, projects, teams or users within + + InfluxDB. + + + Use the `/api/v2/orgs` endpoints to view and manage organizations. + name: Organizations - name: Ping - description: | Retrieve data, analyze queries, and get query suggestions. diff --git a/api-docs/v2.4/ref.yml b/api-docs/v2.4/ref.yml index 2245842ee..c8a485b58 100644 --- a/api-docs/v2.4/ref.yml +++ b/api-docs/v2.4/ref.yml @@ -3284,12 +3284,16 @@ components: $ref: '#/components/schemas/PatchRetentionRules' type: object PatchOrganizationRequest: + description: | + An object that contains updated organization properties to apply. properties: description: - description: New description to set on the organization + description: | + The description of the organization. type: string name: - description: New name to set on the organization + description: | + The name of the organization. type: string type: object PatchRetentionRule: @@ -3503,8 +3507,12 @@ components: PostOrganizationRequest: properties: description: + description: | + The description of the organization. type: string name: + description: | + The name of the organization. type: string required: - name @@ -11888,6 +11896,27 @@ paths: '200': content: application/json: + examples: + successResponse: + value: + links: + self: /api/v2/orgs + orgs: + - createdAt: '2022-07-17T23:00:30.778487Z' + description: Example InfluxDB organization + id: INFLUX_ORG_ID + links: + buckets: /api/v2/buckets?org=INFLUX_ORG + dashboards: /api/v2/dashboards?org=INFLUX_ORG + labels: /api/v2/orgs/INFLUX_ORG_ID/labels + logs: /api/v2/orgs/INFLUX_ORG_ID/logs + members: /api/v2/orgs/INFLUX_ORG_ID/members + owners: /api/v2/orgs/INFLUX_ORG_ID/owners + secrets: /api/v2/orgs/INFLUX_ORG_ID/secrets + self: /api/v2/orgs/INFLUX_ORG_ID + tasks: /api/v2/tasks?org=InfluxData + name: INFLUX_ORG + updatedAt: '2022-07-17T23:00:30.778487Z' schema: $ref: '#/components/schemas/Organizations' description: Success. The response body contains a list of organizations. @@ -11906,12 +11935,23 @@ paths: - Organizations - Security and access endpoints post: - description: | - Creates an organization and returns the newly created organization. + description: > + Creates an + [organization](/influxdb/v2.3/reference/glossary/#organization) + + and returns the newly created organization. + #### InfluxDB Cloud + - Doesn't allow you to use this endpoint to create organizations. + + + #### Related guides + + + - [Manage organizations](/influxdb/v2.3/organizations) operationId: PostOrgs parameters: - $ref: '#/components/parameters/TraceSpan' @@ -11926,13 +11966,35 @@ paths: '201': content: application/json: + examples: + successResponse: + value: + createdAt: '2022-08-24T23:05:52.881317Z' + description: '' + id: INFLUX_ORG_ID + links: + buckets: /api/v2/buckets?org=INFLUX_ORG + dashboards: /api/v2/dashboards?org=INFLUX_ORG + labels: /api/v2/orgs/INFLUX_ORG_ID/labels + logs: /api/v2/orgs/INFLUX_ORG_ID/logs + members: /api/v2/orgs/INFLUX_ORG_ID/members + owners: /api/v2/orgs/INFLUX_ORG_ID/owners + secrets: /api/v2/orgs/INFLUX_ORG_ID/secrets + self: /api/v2/orgs/INFLUX_ORG_ID + tasks: /api/v2/tasks?org=INFLUX_ORG + name: INFLUX_ORG + updatedAt: '2022-08-24T23:05:52.881318Z' schema: $ref: '#/components/schemas/Organization' - description: | - Success. The organization is created. - The response body contains the new organization. + description: Created. The response body contains the organization information. '400': $ref: '#/components/responses/BadRequestError' + examples: + invalidRequest: + summary: The `name` field is missing from the request body. + value: + code: invalid + message: org name is empty '401': $ref: '#/components/responses/AuthorizationError' '404': @@ -11940,16 +12002,59 @@ paths: '500': $ref: '#/components/responses/InternalServerError' default: - $ref: '#/components/responses/GeneralServerError' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + description: Unexpected error summary: Create an organization tags: - Organizations + x-codeSamples: + - label: cURL + lang: Shell + source: | + curl --request POST "http://localhost:8086/api/v2/orgs \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "name": "INFLUX_ORG", + "description: "Example InfluxDB organization" + }' /api/v2/orgs/{orgID}: delete: + description: | + Deletes an organization. + + Deleting an organization from InfluxDB Cloud can't be undone. + Once deleted, all data associated with the organization is removed. + + #### InfluxDB Cloud + + - Does the following when you send a delete request: + + 1. Validates the request and queues the delete. + 2. Returns an HTTP `204` status code if queued; _error_ otherwise. + 3. Handles the delete asynchronously. + + #### InfluxDB OSS + + - Validates the request, handles the delete synchronously, + and then responds with success or failure. + + #### Limitations + + - Only one organization can be deleted per request. + + #### Related guides + + - [Delete organization](/influxdb/v2.3/organizations/delete-orgs/) operationId: DeleteOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the organization to delete. + - description: | + The ID of the organization to delete. in: path name: orgID required: true @@ -11957,13 +12062,35 @@ paths: type: string responses: '204': - description: Delete has been accepted + description: | + Success. + + #### InfluxDB Cloud + - The organization is queued for deletion. + + #### InfluxDB OSS + - The organization is deleted. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' '404': content: application/json: + examples: + notFound: + summary: | + The requested organization was not found. + value: + code: not found + message: org not found schema: $ref: '#/components/schemas/Error' - description: Organization not found + description: | + Not found. + InfluxDB can't find the organization. + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -11974,10 +12101,19 @@ paths: tags: - Organizations get: + description: | + Retrieves an organization. + + Use this endpoint to retrieve information for a specific organization. + + #### Related guides + + - [View organization](/influxdb/v2.3/organizations/view-orgs/) operationId: GetOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the organization to get. + - description: | + The ID of the organization to retrieve. in: path name: orgID required: true @@ -11989,7 +12125,28 @@ paths: application/json: schema: $ref: '#/components/schemas/Organization' - description: Organization details + description: | + Success. + The response body contains the organization information. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + content: + application/json: + examples: + notFound: + summary: | + The requested organization wasn't found. + value: + code: not found + message: organization not found + schema: + $ref: '#/components/schemas/Error' + description: | + Not found. + Organization not found. + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -12001,10 +12158,46 @@ paths: - Organizations - Security and access endpoints patch: + description: > + Updates an organization. + + + Use this endpoint to update properties + + (`name`, `description`) of an organization. + + + Updating an organization’s name affects all resources that reference the + + organization by name, including the following: + + + - Queries + + - Dashboards + + - Tasks + + - Telegraf configurations + + - Templates + + + If you change an organization name, be sure to update the organization + name + + in these resources as well. + + + #### Related Guides + + + - [Update an organization](/influxdb/v2.3/organizations/update-org/) operationId: PatchOrgsID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the organization to get. + - description: | + The ID of the organization to update. in: path name: orgID required: true @@ -12015,7 +12208,7 @@ paths: application/json: schema: $ref: '#/components/schemas/PatchOrganizationRequest' - description: Organization update to apply + description: The organization update to apply. required: true responses: '200': @@ -12023,7 +12216,15 @@ paths: application/json: schema: $ref: '#/components/schemas/Organization' - description: Organization updated + description: Success. The response body contains the updated organization. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -12035,10 +12236,57 @@ paths: - Organizations /api/v2/orgs/{orgID}/members: get: + description: > + Retrieves a list of all users that belong to an organization. + + + InfluxDB [users](/influxdb/v2.3/reference/glossary/#user) have + + permission to access InfluxDB. + + + [Members](/influxdb/v2.3/reference/glossary/#member) are users + + within the organization. + + + #### InfluxDB Cloud + + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + + - Member permissions are separate from API token permissions. + + - Member permissions are used in the context of the InfluxDB UI. + + + #### Required permissions + + + - `read-orgs INFLUX_ORG_ID` + + + `INFLUX_ORG_ID` is the ID of the organization that you retrieve a list + of + + members from. + + + #### Related guides + + + - [Manage users](/influxdb/v2.3/users/) + + - [Manage members](/influxdb/v2.3/organizations/members/) operationId: GetOrgsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. + - description: | + The ID of the organization to retrieve users for. in: path name: orgID required: true @@ -12048,15 +12296,52 @@ paths: '200': content: application/json: + examples: + successResponse: + value: + links: + self: /api/v2/orgs/055aa4783aa38398/members + users: + - id: 791df274afd48a83 + links: + self: /api/v2/users/791df274afd48a83 + name: example_user_1 + role: member + status: active + - id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_2 + role: owner + status: active schema: $ref: '#/components/schemas/ResourceMembers' - description: A list of organization members + description: > + Success. + + The response body contains a list of all users within the + organization. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' '404': content: application/json: + examples: + notFound: + summary: | + The requested organization wasn't found. + value: + code: not found + message: 404 page not found schema: $ref: '#/components/schemas/Error' - description: Organization not found + description: | + Not found. + InfluxDB can't find the organization. + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -12068,10 +12353,54 @@ paths: - Organizations - Security and access endpoints post: + description: > + Add a user to an organization. + + + InfluxDB [users](/influxdb/v2.3/reference/glossary/#user) have + + permission to access InfluxDB. + + + [Members](/influxdb/v2.3/reference/glossary/#member) are users + + within the organization. + + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + + - Member permissions are separate from API token permissions. + + - Member permissions are used in the context of the InfluxDB UI. + + + #### Required permissions + + + - `write-orgs INFLUX_ORG_ID` + + + `INFLUX_ORG_ID` is the ID of the organization that you want add a member + to. + + + #### Related guides + + + - [Manage users](/influxdb/v2.3/users/) + + - [Manage members](/influxdb/v2.3/organizations/members/) operationId: PostOrgsIDMembers parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The organization ID. + - description: | + The ID of the organization. in: path name: orgID required: true @@ -12082,15 +12411,41 @@ paths: application/json: schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' - description: User to add as member + description: | + The user to add to the organization. required: true responses: '201': content: application/json: + examples: + successResponse: + value: + id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_1 + role: member + status: active schema: $ref: '#/components/schemas/ResourceMember' - description: Added to organization created + description: | + Success. + The response body contains the user information. + '400': + $ref: '#/components/responses/BadRequestError' + examples: + invalidRequest: + summary: The user `id` is missing from the request body. + value: + code: invalid + message: user id missing or invalid + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -12100,18 +12455,69 @@ paths: summary: Add a member to an organization tags: - Organizations + x-codeSamples: + - label: cURL + lang: Shell + source: > + curl --request POST + "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/members \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "id": "09cfb87051cbe000" + }' /api/v2/orgs/{orgID}/members/{userID}: delete: + description: > + Removes a member from an organization. + + + Use this endpoint to remove a user's member privileges from a bucket. + This + + removes the user's `read` and `write` permissions from the organization. + + + #### InfluxDB Cloud + + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + + - Member permissions are separate from API token permissions. + + - Member permissions are used in the context of the InfluxDB UI. + + + #### Required permissions + + + - `write-orgs INFLUX_ORG_ID` + + + `INFLUX_ORG_ID` is the ID of the organization that you want to remove an + + owner from. + + + #### Related guides + + + - [Manage members](/influxdb/v2.3/organizations/members/) operationId: DeleteOrgsIDMembersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the member to remove. + - description: The ID of the user to remove. in: path name: userID required: true schema: type: string - - description: The organization ID. + - description: The ID of the organization to remove a user from. in: path name: orgID required: true @@ -12119,7 +12525,15 @@ paths: type: string responses: '204': - description: Member removed + description: | + Success. + The user is no longer a member of the organization. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -12132,8 +12546,26 @@ paths: - Security and access endpoints /api/v2/orgs/{orgID}/owners: get: - description: | + description: > Retrieves a list of all owners of an organization. + + + #### InfluxDB Cloud + + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Required permissions + + + - `read-orgs INFLUX_ORG_ID` + + + `INFLUX_ORG_ID` is the ID of the organization that you want to retrieve + a + + list of owners from. operationId: GetOrgsIDOwners parameters: - $ref: '#/components/parameters/TraceSpan' @@ -12148,6 +12580,18 @@ paths: '200': content: application/json: + examples: + successResponse: + value: + links: + self: /api/v2/orgs/055aa4783aa38398/owners + users: + - id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_2 + role: owner + status: active schema: $ref: '#/components/schemas/ResourceOwners' description: A list of organization owners @@ -12207,6 +12651,15 @@ paths: requestBody: content: application/json: + examples: + successResponse: + value: + id: 09cfb87051cbe000 + links: + self: /api/v2/users/09cfb87051cbe000 + name: example_user_1 + role: owner + status: active schema: $ref: '#/components/schemas/AddResourceMemberRequestBody' description: The user to add as an owner of the organization. @@ -12220,6 +12673,14 @@ paths: description: | Success. The user is an owner of the organization. The response body contains the owner with role and user detail. + '400': + $ref: '#/components/responses/BadRequestError' + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -12229,18 +12690,71 @@ paths: summary: Add an owner to an organization tags: - Organizations + x-codeSamples: + - label: cURL + lang: Shell + source: > + curl --request POST + "http://localhost:8086/api/v2/orgs/INFLUX_ORG_ID/owners \ + --header "Authorization: Token INFLUX_API_TOKEN" \ + --header "Accept: application/json" \ + --header "Content-Type: application/json" \ + --data '{ + "id": "09cfb87051cbe000" + }' /api/v2/orgs/{orgID}/owners/{userID}: delete: + description: > + Removes an [owner](/influxdb/v2.3/reference/glossary/#owner) from + + the organization. + + + Organization owners have permission to delete organizations and remove + user and member + + permissions from the organization. + + + #### InfluxDB Cloud + + - Doesn't use `owner` and `member` roles. + Use [`/api/v2/authorizations`](#tag/Authorizations) to assign user permissions. + + #### Limitations + + + - Owner permissions are separate from API token permissions. + + - Owner permissions are used in the context of the InfluxDB UI. + + + #### Required permissions + + + - `write-orgs INFLUX_ORG_ID` + + + `INFLUX_ORG_ID` is the ID of the organization that you want remove an + owner + + from. + + + #### Related endpoints + + - [Authorizations](#tag/Authorizations) operationId: DeleteOrgsIDOwnersID parameters: - $ref: '#/components/parameters/TraceSpan' - - description: The ID of the owner to remove. + - description: The ID of the user to remove. in: path name: userID required: true schema: type: string - - description: The organization ID. + - description: | + The ID of the organization to remove an owner from. in: path name: orgID required: true @@ -12248,7 +12762,15 @@ paths: type: string responses: '204': - description: Owner removed + description: | + Success. + The user is no longer an owner of the organization. + '401': + $ref: '#/components/responses/AuthorizationError' + '404': + $ref: '#/components/responses/ResourceNotFoundError' + '500': + $ref: '#/components/responses/InternalServerError' default: content: application/json: @@ -19551,7 +20073,20 @@ tags: - name: Metrics - name: NotificationEndpoints - name: NotificationRules - - name: Organizations + - description: > + Create and manage your + [organizations](/influxdb/v2.3/reference/glossary/#organization). + + An organization is a workspace for a group of users. Organizations can be + + used to separate different environments, projects, teams or users within + + InfluxDB. + + + Use the `/api/v2/orgs` endpoints to create, view, and manage + organizations. + name: Organizations - name: Ping - description: | Retrieve data, analyze queries, and get query suggestions. From b15e37b144671c6136f1a67c5bf6cd9a6a36910e Mon Sep 17 00:00:00 2001 From: sunbryely-influxdata <101659702+sunbryely-influxdata@users.noreply.github.com> Date: Fri, 9 Sep 2022 10:09:00 -0700 Subject: [PATCH 2/5] Update api-docs/cloud/ref.yml Co-authored-by: Jason Stirnaman --- api-docs/cloud/ref.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-docs/cloud/ref.yml b/api-docs/cloud/ref.yml index 04d9273b2..668b67136 100644 --- a/api-docs/cloud/ref.yml +++ b/api-docs/cloud/ref.yml @@ -11415,7 +11415,7 @@ paths: - Security and access endpoints post: description: > - Add a user to an organization. + Adds a user to an organization. InfluxDB [users](/influxdb/cloud/reference/glossary/#user) have From df953e01e8b128701390e5542d89ed1ee9314437 Mon Sep 17 00:00:00 2001 From: sunbryely-influxdata <101659702+sunbryely-influxdata@users.noreply.github.com> Date: Fri, 9 Sep 2022 10:09:07 -0700 Subject: [PATCH 3/5] Update api-docs/cloud/ref.yml Co-authored-by: Jason Stirnaman --- api-docs/cloud/ref.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-docs/cloud/ref.yml b/api-docs/cloud/ref.yml index 668b67136..bb39a7624 100644 --- a/api-docs/cloud/ref.yml +++ b/api-docs/cloud/ref.yml @@ -11492,7 +11492,7 @@ paths: $ref: '#/components/schemas/ResourceMember' description: | Success. - The response body contains the user information. + The response body contains the user. '400': $ref: '#/components/responses/BadRequestError' examples: From 6b7aba002964c4a7ec77fb119427ff5366ccd007 Mon Sep 17 00:00:00 2001 From: sunbryely-influxdata <101659702+sunbryely-influxdata@users.noreply.github.com> Date: Fri, 9 Sep 2022 10:09:23 -0700 Subject: [PATCH 4/5] Update api-docs/cloud/ref.yml Co-authored-by: Jason Stirnaman --- api-docs/cloud/ref.yml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/api-docs/cloud/ref.yml b/api-docs/cloud/ref.yml index bb39a7624..d43efda90 100644 --- a/api-docs/cloud/ref.yml +++ b/api-docs/cloud/ref.yml @@ -11534,10 +11534,7 @@ paths: Removes a member from an organization. - Use this endpoint to remove a user's member privileges from a bucket. - This - - removes the user's `read` and `write` permissions from the organization. + Use this endpoint to remove a user's `read` and `write` permissions for the organization. #### InfluxDB Cloud From 1ba9d6fa1ddeafb5795af20169228166b9764382 Mon Sep 17 00:00:00 2001 From: sunbryely-influxdata <101659702+sunbryely-influxdata@users.noreply.github.com> Date: Fri, 9 Sep 2022 10:09:43 -0700 Subject: [PATCH 5/5] Update api-docs/v2.4/ref.yml Co-authored-by: Jason Stirnaman --- api-docs/v2.4/ref.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api-docs/v2.4/ref.yml b/api-docs/v2.4/ref.yml index c8a485b58..64f6e1620 100644 --- a/api-docs/v2.4/ref.yml +++ b/api-docs/v2.4/ref.yml @@ -12354,7 +12354,7 @@ paths: - Security and access endpoints post: description: > - Add a user to an organization. + Adds a user to an organization. InfluxDB [users](/influxdb/v2.3/reference/glossary/#user) have