docs: add reference for fix plan API endpoints #2696

lucasmoura · 2023-08-04T21:30:17Z

Why is this needed?

Add references for the fix plan API endpoints that will be released in the next Pro release

orndorffgrant

I think defining the complete nested return type for each endpoint makes sense. I think trying to refer to a common definition would be harder to follow

docs/references/api.rst

orndorffgrant · 2023-08-10T19:42:30Z

docs/references/api.rst

+               - *List[FixPlanResult]*
+               - A list of FixPlanResult objects
+
+        - ``uaclient.api.u.pro.security.fix import FixPlanResult``


It wasn't until seeing it laid out in our docs like this that I realized: This is an unversioned return type :/

This is what we're releasing and it's okay, but we should consider changing it next release. I think all return types should be tied directly to the version of the endpoint they're used in. So I think ideally this might get defined in something like api.u.pro.security.fix._common.v1.FixPlanResult, but we wouldn't tell users about that - instead we'd import and re-export as api.u.pro.security.fix.cve.plan.v1.FixPlanResult so then the complete nested return type is all defined in the module of the endpoint itself.

That's an excellent point and I will make this change for the next release

+1
I went ahead and created #2714 and assigned it to you

lucasmoura · 2023-08-23T16:38:07Z

@orndorffgrant updated

orndorffgrant

Just some nits

orndorffgrant · 2023-08-23T21:11:29Z

docs/references/api.rst

+
+  For example: `pro api u.pro.attach.magic.revoke.v1 --args magic_token=TOKEN`
+
+* ``data``: Use this to provide a JSON object containing all the data:


Let's include the -- to make it consistent with --args

Suggested change

* ``data``: Use this to provide a JSON object containing all the data:

* ``--data``: Use this to provide a JSON object containing all the data:

orndorffgrant · 2023-08-23T21:11:46Z

docs/references/api.rst

+
+* ``--args``: Use this to individually provide arguments to the CLI endpoint.
+
+  For example: `pro api u.pro.attach.magic.revoke.v1 --args magic_token=TOKEN`


Currently this is italics

Suggested change

For example: `pro api u.pro.attach.magic.revoke.v1 --args magic_token=TOKEN`

For example: ``pro api u.pro.attach.magic.revoke.v1 --args magic_token=TOKEN``

orndorffgrant · 2023-08-23T21:11:55Z

docs/references/api.rst

+
+* ``data``: Use this to provide a JSON object containing all the data:
+
+  For example: `pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-1234-1235"]}'`


Suggested change

For example: `pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-1234-1235"]}'`

For example: ``pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-1234-1235"]}'``

orndorffgrant · 2023-08-25T14:37:08Z

docs/references/api.rst

+               - *List[FixPlanResult]*
+               - A list of FixPlanResult objects
+
+        - ``uaclient.api.u.pro.security.fix import FixPlanResult``


+1
I went ahead and created #2714 and assigned it to you

orndorffgrant · 2023-08-25T14:38:07Z

docs/references/api.rst

+
+        .. code-block:: bash
+
+           pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": [...]}'


I think we might as well include the sample example cve strings as the python example

Suggested change

pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": [...]}'

pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-1234-1234", "CVE-1234-1235"]}'

orndorffgrant · 2023-08-25T14:39:46Z

docs/references/api.rst

+
+           from uaclient.api.u.pro.security.fix.usn.plan.v1 import plan, USNFixPlanOptions
+
+           options = USNFixPlanOptions(cves=["USN-1234-1", "CVE-1235-1"])


This includes a CVE in the example

Suggested change

options = USNFixPlanOptions(cves=["USN-1234-1", "CVE-1235-1"])

options = USNFixPlanOptions(cves=["USN-1234-1", "USN-1235-1"])

orndorffgrant · 2023-08-25T14:39:56Z

docs/references/api.rst

+
+        .. code-block:: bash
+
+           pro api u.pro.security.fix.usn.plan.v1 --data '{"usns": [...]}'


Same comment as above

Suggested change

pro api u.pro.security.fix.usn.plan.v1 --data '{"usns": [...]}'

pro api u.pro.security.fix.usn.plan.v1 --data '{"usns": ["USN-1234-1", "USN-1235-1"]}'

s-makin

Just two quick nits, otherwise I think this should be good to go

s-makin · 2023-08-31T10:58:19Z

docs/references/api.rst

+- Introduced in Ubuntu Pro Client Version: ``29~``
+- Args:
+
+  - ``cves``: A list of CVEs (i.e CVE-2023-2650) titles


Suggested change

- ``cves``: A list of CVEs (i.e CVE-2023-2650) titles

- ``cves``: A list of CVE (i.e. CVE-2023-2650) titles

s-makin · 2023-08-31T11:10:45Z

docs/references/api.rst

+- Introduced in Ubuntu Pro Client Version: ``29~``
+- Args:
+
+  - ``usns``: A list of USNs (i.e CVE-6188-1) titles


I'm not sure if this is intended or not, but a couple of times in this section about the usn endpoint there are references to CVE (like here). Might be worth a double-check to make sure that any references to CVE for this endpoint are intended (I'm not sure!)

Good catch @s-makin, this is indeed incorrect. I will fix that

lucasmoura · 2023-09-01T19:10:41Z

@orndorffgrant @s-makin updated

s-makin

LGTM :) thanks for all your work on this

lucasmoura marked this pull request as draft August 4, 2023 21:31

lucasmoura force-pushed the fix-plan-api-doc branch from d1150c7 to edcdcf4 Compare August 7, 2023 12:53

lucasmoura changed the base branch from docs to docs-devel August 8, 2023 13:47

lucasmoura force-pushed the fix-plan-api-doc branch from edcdcf4 to a75570c Compare August 10, 2023 14:48

orndorffgrant reviewed Aug 10, 2023

View reviewed changes

lucasmoura force-pushed the fix-plan-api-doc branch from a75570c to ddbf76a Compare August 23, 2023 16:37

lucasmoura marked this pull request as ready for review August 23, 2023 16:38

orndorffgrant reviewed Aug 25, 2023

View reviewed changes

s-makin reviewed Aug 31, 2023

View reviewed changes

docs: add reference for fix plan API endpoints

4a71a78

lucasmoura force-pushed the fix-plan-api-doc branch from ddbf76a to 4a71a78 Compare September 1, 2023 19:10

s-makin approved these changes Sep 4, 2023

View reviewed changes

orndorffgrant approved these changes Sep 5, 2023

View reviewed changes

orndorffgrant merged commit 1883434 into docs-devel Sep 5, 2023
3 checks passed

orndorffgrant deleted the fix-plan-api-doc branch September 5, 2023 16:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add reference for fix plan API endpoints #2696

docs: add reference for fix plan API endpoints #2696

lucasmoura commented Aug 4, 2023

orndorffgrant left a comment

orndorffgrant Aug 10, 2023

lucasmoura Aug 23, 2023

orndorffgrant Aug 25, 2023

lucasmoura commented Aug 23, 2023

orndorffgrant left a comment

orndorffgrant Aug 23, 2023

orndorffgrant Aug 23, 2023

orndorffgrant Aug 23, 2023

orndorffgrant Aug 25, 2023

orndorffgrant Aug 25, 2023

orndorffgrant Aug 25, 2023

orndorffgrant Aug 25, 2023

s-makin left a comment

s-makin Aug 31, 2023

s-makin Aug 31, 2023

lucasmoura Sep 1, 2023

lucasmoura commented Sep 1, 2023

s-makin left a comment


		For example: `pro api u.pro.attach.magic.revoke.v1 --args magic_token=TOKEN`

		* ``data``: Use this to provide a JSON object containing all the data:

	* ``data``: Use this to provide a JSON object containing all the data:
	* ``--data``: Use this to provide a JSON object containing all the data:


		* ``--args``: Use this to individually provide arguments to the CLI endpoint.

		For example: `pro api u.pro.attach.magic.revoke.v1 --args magic_token=TOKEN`

	For example: `pro api u.pro.attach.magic.revoke.v1 --args magic_token=TOKEN`
	For example: ``pro api u.pro.attach.magic.revoke.v1 --args magic_token=TOKEN``


		* ``data``: Use this to provide a JSON object containing all the data:

		For example: `pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-1234-1235"]}'`

	For example: `pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-1234-1235"]}'`
	For example: ``pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": ["CVE-1234-1235"]}'``


		.. code-block:: bash

		pro api u.pro.security.fix.cve.plan.v1 --data '{"cves": [...]}'


		from uaclient.api.u.pro.security.fix.usn.plan.v1 import plan, USNFixPlanOptions

		options = USNFixPlanOptions(cves=["USN-1234-1", "CVE-1235-1"])


		.. code-block:: bash

		pro api u.pro.security.fix.usn.plan.v1 --data '{"usns": [...]}'

	- ``cves``: A list of CVEs (i.e CVE-2023-2650) titles
	- ``cves``: A list of CVE (i.e. CVE-2023-2650) titles

docs: add reference for fix plan API endpoints #2696

docs: add reference for fix plan API endpoints #2696

Conversation

lucasmoura commented Aug 4, 2023

Why is this needed?

orndorffgrant left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lucasmoura commented Aug 23, 2023

orndorffgrant left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

s-makin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lucasmoura commented Sep 1, 2023

s-makin left a comment

Choose a reason for hiding this comment