Chore/api reference scripts delete by sunbryely-influxdata · Pull Request #444 · influxdata/openapi

sunbryely-influxdata · 2022-07-19T22:47:28Z

Delete script
Get script
Patch script

jstirnaman · 2022-08-16T17:07:53Z

-    Updates properties (`name`, `description`, and `script`) of an invokable script.
+    Updates an invokable script.
+
+    Use this endpoint to update the properties (`description`, and `script`)


Suggested change

Use this endpoint to update the properties (`description`, and `script`)

Use this endpoint to modify values for script properties (`description` and `script`).

jstirnaman · 2022-08-16T17:08:41Z

+    Updates an invokable script.
+
+    Use this endpoint to update the properties (`description`, and `script`)
+    of an invokable script.


Suggested change

of an invokable script.

jstirnaman · 2022-08-16T17:21:35Z

+
+    #### Limitations
+
+    - Sending an empty request body returns an HTTP `200` status code.


Suggested change

- Sending an empty request body returns an HTTP `200` status code.

- If you send an empty request body, InfluxDB responds with an HTTP `200` status code.

jstirnaman · 2022-08-16T17:22:20Z

+          examples:
+            notFound:
+              summary: |
+                The requested script was not found.


Suggested change

The requested script was not found.

The requested script wasn't found.

jstirnaman · 2022-08-16T17:26:26Z

+
+    #### Limitations
+
+    - Only one script can be deleted per request.


Suggested change

- Only one script can be deleted per request.

- You can delete only one script per request.

jstirnaman · 2022-08-16T17:31:23Z

+    #### Limitations
+
+    - Only one script can be deleted per request.
+    - `scriptIDs` that do not exist return an HTTP `204` status code.


Suggested change

- `scriptIDs` that do not exist return an HTTP `204` status code.

- If the script ID you provide doesn't exist for the organization, InfluxDB responds with an HTTP `204` status code.

jstirnaman

Fix and a question

jstirnaman · 2022-08-18T20:12:49Z

+        Script ID.
+        Only returns the script with this ID.


Suggested change

Script ID.

Only returns the script with this ID.

The ID of the script to retrieve.

I suppose we could apply that same pattern (like you did here) to all the GET ...${ID} operations. Makes things easier for us and is more descriptive.
I've following Square's convention with "The ID of the...".
What do you think? We should still lead with the article, though: "The script ID."

I think i like how square is wording it. "The ID of the..." sounds good to me

jstirnaman · 2022-08-18T20:13:17Z

+    #### Limitations
+
+    - You can delete only one script per request.
+    - If the script ID you provide doesnt exist for the organization, InfluxDB


Suggested change

- If the script ID you provide doesnt exist for the organization, InfluxDB

- If the script ID you provide doesn't exist for the organization, InfluxDB

jstirnaman · 2022-08-18T20:13:40Z

      required: true
-      description: The ID of the script to delete.
+      description: |
+        Script ID.


Suggested change

Script ID.

The script ID.

jstirnaman · 2022-08-29T14:08:50Z

-    Updates properties (`name`, `description`, and `script`) of an invokable script.
+    Updates an invokable script.
+
+    Use this endpoint to modify values for script properties (`description`, and `script`).


Suggested change

Use this endpoint to modify values for script properties (`description`, and `script`).

Use this endpoint to modify values for script properties (`description` and `script`).

jstirnaman · 2022-08-29T14:10:44Z

+
+    #### Limitations
+
+    - If you send an empty request body, InfluxDB responds with an HTTP `200`


Does this store an empty script?

It does not store an empty script. i'll add an additional statement saying that it does not store an empty script / does not update the script

jstirnaman · 2022-08-29T14:11:36Z

+    #### Limitations
+
+    - You can delete only one script per request.
+    - If the script ID you provide doesn't exist for the organization, InfluxDB


jstirnaman · 2022-09-07T15:51:17Z

-      description: The requested script object.
+      description: |
+        Success.
+        The response body contains the script object.


Suggested change

The response body contains the script object.

The response body contains the script detail.

jstirnaman · 2022-09-07T15:53:34Z

+
+    #### Limitations
+
+    - If you send an empty request body, the script will neither update nor


It doesn't create a script object with an empty script?

jstirnaman · 2022-09-07T15:57:23Z

  requestBody:
-    description: Script update to apply
+    description: |
+      An object that contains the updated script properties to apply.


My preference is to avoid mentioning "object" given that it's content-type (JSON) specific... even though it's the only content-type. I'm sure I break this rule occasionally.

e.g. See how https://developers.google.com/youtube/v3/docs/playlistItems/insert?hl=en_US and https://developer.squareup.com/reference/square/payments-api/create-payment both avoid using content-type specific language. YouTube uses more HTTP/REST-ish descriptions like `resource' with a link to the schema entity. Square doesn't usually describe the payload as a thing, just the "Payment" and the fields.

I think what you did is more practical, but maybe we could show it with an example instead of describe it.

jstirnaman · 2022-09-07T16:08:29Z

      required: true
-      description: The script ID.
+      description: |
+        Script ID.


Suggested change

Script ID.

jstirnaman · 2022-09-07T16:08:57Z

+      source: |
+        curl -X 'PATCH' \
+          "https://cloud2.influxdata.com/api/v2/scripts/SCRIPT_ID" \
+          --header "Authorization: Token INFLUX_TOKEN" \


Suggested change

--header "Authorization: Token INFLUX_TOKEN" \

--header "Authorization: Token INFLUX_API_TOKEN" \

jstirnaman · 2022-09-07T16:10:19Z

+          --header "Accept: application/json"
+          --header "Content-Type: application/json"
+          --data '{
+              "description": "get last point from new bucket",


Suggested change

"description": "get last point from new bucket",

"description": "Get the last point from the bucket",

Resolved

jstirnaman

🎊

jstirnaman · 2022-11-04T23:14:27Z

-    Use this endpoint to update the properties (`name`, `description`, and `script`) of an invokable script.
+    Use this endpoint to modify values for script properties (`description` and `script`).
+
+    To update a script, pass an object that contains the updated key-value pairs.


Let's use the requestBody description for this and not duplicate.

Suggested change

To update a script, pass an object that contains the updated key-value pairs.

jstirnaman · 2022-11-04T23:16:16Z

  requestBody:
-    description: The script update to apply.
+    description: |
+      An object that contains the updated script properties to apply.


Suggested change

An object that contains the updated script properties to apply.

In the request body, provide the script properties to update.

This is my new pattern. Eventually, I plan to append an statement (with redoc-cli) that introduces the properties that can be set, like in YouTube docs--"You can set the following properties for this resource:"

* 'master' of github.com:influxdata/openapi: chore: use /latest alias for OSS URL substitutions. (#603) fix(bucket schemas): `requestBody` for `createMeasurementSchema` and `updateMeasurementSchema` should be required (#607) fix(tasks): `orgID` should not be required for GetTasks (#606) chore(aim): Add Operator Entitlements Endpoints (#595) chore(aim): Add 403 to Org Creation Endpoints (#597) chore(invocable-scripts): add /api/v2/scripts/SCRIPT_ID/params (#593) Chore/api reference scripts delete (#444)

Sunbrye Ly added 6 commits July 19, 2022 13:27

feat: delete and getID

59b5848

contracts

2758b81

feat: patch

ac8a608

linting

e81705b

lint

1b35d84

feat: finished draft

6689332

sunbryely-influxdata marked this pull request as ready for review July 19, 2022 23:38

sunbryely-influxdata requested a review from a team as a code owner July 19, 2022 23:38

sunbryely-influxdata requested review from jstirnaman and sanderson and removed request for a team July 19, 2022 23:38

sanderson approved these changes Jul 22, 2022

View reviewed changes

jstirnaman requested changes Jul 25, 2022

View reviewed changes

fix: pr requested changes

a9b13b0

sunbryely-influxdata requested a review from jstirnaman July 26, 2022 21:47

jstirnaman requested changes Jul 27, 2022

View reviewed changes

fix: requested PR changes

94fc60e

sunbryely-influxdata requested a review from jstirnaman August 15, 2022 22:04

jstirnaman requested changes Aug 16, 2022

View reviewed changes

Sunbrye Ly added 2 commits August 17, 2022 17:29

Merge branch 'master' into chore/api-reference-scripts-delete

70cb572

fix: pr requested changes

310fa28

sunbryely-influxdata requested a review from jstirnaman August 18, 2022 00:42

jstirnaman requested changes Aug 18, 2022

View reviewed changes

fix: requested PR changes

959bda4

sunbryely-influxdata requested a review from jstirnaman August 22, 2022 21:50

jstirnaman requested changes Aug 29, 2022

View reviewed changes

fix: pr requested changes

5581a91

sunbryely-influxdata requested a review from jstirnaman August 29, 2022 18:08

jstirnaman previously requested changes Sep 7, 2022

View reviewed changes

fix: rebase

c230ca4

sunbryely-influxdata requested a review from jstirnaman November 4, 2022 23:10

sunbryely-influxdata merged commit 26b604e into master Nov 4, 2022

sunbryely-influxdata deleted the chore/api-reference-scripts-delete branch November 4, 2022 23:11

jstirnaman approved these changes Nov 4, 2022

View reviewed changes

jstirnaman mentioned this pull request Nov 4, 2022

docs: fix script description #605

Open

	Use this endpoint to update the properties (`description`, and `script`)
	Use this endpoint to modify values for script properties (`description` and `script`).


		#### Limitations

		- Sending an empty request body returns an HTTP `200` status code.

	- Sending an empty request body returns an HTTP `200` status code.
	- If you send an empty request body, InfluxDB responds with an HTTP `200` status code.

	The requested script was not found.
	The requested script wasn't found.


		#### Limitations

		- Only one script can be deleted per request.

	- Only one script can be deleted per request.
	- You can delete only one script per request.

	- `scriptIDs` that do not exist return an HTTP `204` status code.
	- If the script ID you provide doesn't exist for the organization, InfluxDB responds with an HTTP `204` status code.

	Script ID.
	Only returns the script with this ID.
	The ID of the script to retrieve.

	- If the script ID you provide doesnt exist for the organization, InfluxDB
	- If the script ID you provide doesn't exist for the organization, InfluxDB

	The response body contains the script object.
	The response body contains the script detail.


		#### Limitations

		- If you send an empty request body, the script will neither update nor

	--header "Authorization: Token INFLUX_TOKEN" \
	--header "Authorization: Token INFLUX_API_TOKEN" \

	"description": "get last point from new bucket",
	"description": "Get the last point from the bucket",

	An object that contains the updated script properties to apply.
	In the request body, provide the script properties to update.

Conversation

sunbryely-influxdata commented Jul 19, 2022

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jstirnaman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jstirnaman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants