Upstreamize API guide #3212

Lennonka · 2024-08-12T23:02:39Z

Offering the API guide to Foreman community.

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.12

github-actions · 2024-08-12T23:04:22Z

The PR preview for 1cf4cf8 is available at theforeman-foreman-documentation-preview-pr-3212.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

Lennonka · 2024-08-19T23:58:59Z

Now is the good time to address any changes in the content. Afterwards, I will move the assemblies and modules to common/*.

Lennonka · 2024-08-27T12:18:33Z

Rebased.

Lennonka · 2024-08-27T12:21:13Z

Dropped fake Hammer URL attribute.

maximiliankolb

26/52. Looks good so far; only minor suggestions.

guides/common/attributes-base.adoc

guides/doc-Project_API/master.adoc

guides/doc-Project_API/topics/con_api-cheat-sheet.adoc

guides/doc-Project_API/topics/con_overview-of-the-project-api.adoc

guides/doc-Project_API/topics/con_project-api-compared-to-hammer-cli.adoc

guides/doc-Project_API/topics/con_ssl-authentication-overview.adoc

maximiliankolb

some more suggestions. I did not yet test any of the scripts, but I wonder in general: Can we move certain Python/Ruby/Bash scripts from foreman-documentation to foreman/foreman_maintain? I am unsure if it's a good idea to keep that much code in the docs git repo. (not blocking your PR; could be a future RFC/RFE)

51/52 done. API permissions matrix left.

maximiliankolb · 2024-08-27T12:48:23Z

guides/doc-Project_API/topics/proc_applying-errata-to-a-host-or-host-collection.adoc

+[id="applying-errata-to-a-host-or-host-collection"]
+= Applying errata to a host or host collection
+
+You can use the API to apply errata to a host, host group, or host collection.


Intro does not match anchor/title/file name.

Maybe a generic title such as "Applying errata to hosts by using {Project} API"?

I also wonder: how should be name these files in general? I assume there's already a file "proc_applying-errata-to-hosts.doc" which houses the WebUI/Hammer CLI procedures.

What's our (future!) convention with titles/file names/anchors?

Should we add the API procedure to the "normal"/existing procedure? Aka. is it a good idea to split off procedure by means to interacting with Foreman?

cc @asteflova + @apinnick

FYI: not blocking your PR!

* Should we add the API procedure to the "normal"/existing procedure? Aka. is it a good idea to split off procedure by means to interacting with Foreman?

That's a good point. I can imagine that a more thorough review of how to actually merge the new API modules with the existing guides will be required (what I can't imagine is who would have the capacity for it in the foreseeable future 🙃). For example, some time ago, I used the API guide's overview module and added it (with a few edits) to the Overview guide: https://docs.theforeman.org/nightly/Planning_for_Project/index-katello.html#API-Overview_planning This module will now effectively be duplicated but it works well within the Overview guide. There may be more modules like that that would fit well in the existing guides.

Adding the API procedures from the API guide to appear alongside the CLI and web UI procedures (and also Ansible procedures) seems like a good idea. It would take a lot of effort, though.

guides/doc-Project_API/topics/proc_applying-errata-to-a-host-or-host-collection.adoc

guides/doc-Project_API/topics/proc_using-the-put-http-method.adoc

guides/doc-Project_API/topics/proc_working-with-hosts.adoc

guides/doc-Project_API/topics/proc_working-with-pulp.adoc

guides/doc-Project_API/topics/ref_api-permissions-matrix.adoc

guides/doc-Project_API/topics/proc_using-the-put-http-method.adoc

Lennonka · 2024-08-28T19:28:25Z

Re. API permission matrix

We can use a script similar to this to generate the table: https://github.com/theforeman/foreman-documentation/blob/master/guides/common/modules/proc_creating-a-complete-permission-table.adoc

Or we can just link to it or include it instead 👀

cc @maximiliankolb @asteflova

guides/doc-Project_API/master.adoc

Small changes only Co-authored-by: Maximilian Kolb <[email protected]>

Lennonka · 2024-09-02T19:13:13Z

I fixed some Vale errors. The remaining ones look like false positives to me. Feel free to check.

guides/common/modules/con_oauth-authentication-overview.adoc

maximiliankolb

31/49

almost all comments are mere suggestions and could also get applied in a follow-up PR

guides/common/modules/con_api-request-composition.adoc

guides/common/modules/proc_uploading-content-to-projectserver.adoc

guides/common/modules/proc_applying-errata-to-hosts.adoc

guides/common/modules/proc_calling-the-api-in-curl.adoc

maximiliankolb · 2024-09-03T09:47:09Z

guides/common/modules/proc_calling-the-api-in-curl.adoc

+These API calls require that you pass data in `json` format with the API call.
+For more information, see xref:sect-API_Guide-Passing_JSON_Data_with_the_API_Request[].
+
+[id="ex-API_Guide-Creating_a_New_User"]


Suggested change

[id="ex-API_Guide-Creating_a_New_User"]

[id="creating-a-user"]

looking at this anchor, I wonder if it makes sense to prefix all those anchors with either "api-" or "api-example-"; or add a "-through-api" or "-by-using-{project-context}-api" suffix?

I lean towards a short and sweet "api-" prefix similar to CLI procedures. Then, when we eventually move (or not!) those examples to the "creating users" procedure, the anchors will align/not break.

I like the idea of api- prefix.

I think these anchors aren't that important. Please, change them in a follow-up PR.

guides/common/modules/proc_calling-the-api-in-curl.adoc

guides/common/modules/proc_calling-the-api-in-python.adoc

Lennonka · 2024-09-03T10:53:00Z

guides/common/modules/proc_calling-the-api-in-ruby.adoc

+== Using apipie bindings with Ruby
+
+Apipie bindings are the Ruby bindings for apipie documented API calls.
+They fetch and cache the API definition from {Project} and then generate API calls on demand.


Suggested change

They fetch and cache the API definition from {Project} and then generate API calls on demand.

They fetch and cache the API definition from {Project} and then generate API calls on-demand.

@apinnick I'm not sure what is correct in this case. Can you please weigh in?

Co-authored-by: Maximilian Kolb <[email protected]>

Lennonka · 2024-09-03T10:54:27Z

@maximiliankolb I hesitate to modify the IDs without checking xrefs. I'd prefer to change them in another PR.

…adoc Co-authored-by: Maximilian Kolb <[email protected]>

adamruzicka · 2024-09-03T14:04:19Z

guides/common/modules/proc_configuring-oauth.adoc

+By default, {Project} authorizes all OAuth API requests as the built-in anonymous API administrator account.
+Therefore, API responses include all {Project} data.
+However, you can also specify the {Project} user that makes the request and restrict access to data to that user.
+
+To enable OAuth user mapping, enter the following command:
+
+[options="nowrap", subs="+quotes,attributes"]
+----
+# {foreman-installer} --foreman-oauth-map-users true
+----


IIRC deploying a new content proxy relies on oauth and I'm not sure what enabling user mapping does to it, if anything. @ekohl could you please chime in?

maximiliankolb

39/49. Will do the rest tomorrow. Let's do headings and minor formatting/emphasis in a follow-up PR.

guides/common/modules/ref_json-response-format.adoc

guides/common/modules/ref_api-response-codes.adoc

guides/common/modules/proc_deleting-openscap-reports.adoc

guides/common/modules/proc_modifying-a-smart-class-parameter-by-using-an-external-file.adoc

maximiliankolb

41/49 done; will finish this tomorrow.

guides/common/modules/proc_overriding-smart-class-parameters.adoc

maximiliankolb · 2024-09-05T11:18:42Z

guides/common/modules/proc_uploading-content-to-projectserver.adoc

+
+[id="proc-API_Guide-Uploading_Content_to_the_{Project}_Server"]
+.Procedure
+. Assign the package name to the variable `name`:


I'd drop the trailing colon on 17; and similar on 25 and others.

Alternative suggestion but much more work: get rid of "Example request" everywhere. It's an API documentation; we're not wizards: of course it's an example.

Not blocking.

guides/common/modules/proc_uploading-content-to-projectserver.adoc

guides/common/modules/proc_working-with-lifecycle-environments.adoc

Co-authored-by: Maximilian Kolb <[email protected]>

Lennonka · 2024-09-05T21:31:44Z

I would prefer further changes in subsequent PRs.

maximiliankolb

49/49 🎉

I found many minor cosmetic suggestions from anchors, cli argument orders, example values, emphasis, etc. None of this blocks, in my perspective, this PR. As discussed on Monday, it's been part of Satellite downstream docs as-is for a long time. Therefore, I propose to merge as is and then iterate.

@Lennonka I am OK if you decide on a per-thread basis to apply more changes or to keep it as is. My only concern is that we need to track all SME feedback from this PR.

I would be happy to start working on all those things next week.

guides/common/modules/proc_uploading-content-to-projectserver.adoc

guides/common/modules/proc_calling-the-api-in-curl.adoc

Lennonka · 2024-09-06T08:17:14Z

I am OK if you decide on a per-thread basis to apply more changes or to keep it as is. My only concern is that we need to track all SME feedback from this PR.

Let's create some Issues :)

Co-authored-by: Maximilian Kolb <[email protected]>

Lennonka · 2024-09-06T09:07:55Z

Cherry-picked:

4880f92..cd7b2a1 3.12 -> 3.12

maximiliankolb · 2024-09-06T10:28:22Z

Thanks Lena!

pr-processor bot added the Not yet reviewed label Aug 12, 2024

Lennonka force-pushed the upstreamize-api-guide branch from 70d7ab1 to 849002e Compare August 12, 2024 23:38

This comment was marked as outdated.

Sign in to view

Lennonka mentioned this pull request Aug 13, 2024

Upstreamize Hammer guide #3197

Merged

3 tasks

Lennonka marked this pull request as ready for review August 19, 2024 23:58

Lennonka requested a review from maximiliankolb August 26, 2024 12:39

Lennonka force-pushed the upstreamize-api-guide branch from a916347 to f8b2dfa Compare August 27, 2024 12:18

Lennonka force-pushed the upstreamize-api-guide branch from f8b2dfa to 6cda27b Compare August 27, 2024 12:20

maximiliankolb reviewed Aug 27, 2024

View reviewed changes

guides/doc-Project_API/topics/ref_api-permissions-matrix.adoc Outdated Show resolved Hide resolved

Lennonka commented Aug 27, 2024

View reviewed changes

guides/doc-Project_API/topics/proc_using-the-put-http-method.adoc Outdated Show resolved Hide resolved

pr-processor bot removed the Not yet reviewed label Aug 28, 2024

Lennonka commented Aug 28, 2024

View reviewed changes

guides/doc-Project_API/master.adoc Show resolved Hide resolved

Lennonka and others added 11 commits August 29, 2024 08:55

Add API guide files and metadata

7009b55

Run upstreamize script

fe45387

Upstreamize manually

fb50ccf

Clean up sources files

6f49b49

Change title

a5c528e

Remove templates

bc59d7c

fixup! Change title

6810256

Hide feedback module for non-Satellite

96c75e9

Fix guide link

bec1136

Apply suggestions from review

b406a24

Small changes only Co-authored-by: Maximilian Kolb <[email protected]>

Fix appendixes

8b0e523

Fix Vale errors

fa330d4

Lennonka commented Sep 2, 2024

View reviewed changes

guides/common/modules/con_oauth-authentication-overview.adoc Outdated Show resolved Hide resolved

Fix Vale error

1aae3ae

maximiliankolb reviewed Sep 3, 2024

View reviewed changes

Lennonka commented Sep 3, 2024

View reviewed changes

Apply suggestions from review

5c6d6b8

Co-authored-by: Maximilian Kolb <[email protected]>

Update guides/common/modules/proc_uploading-content-to-projectserver.…

4dc791f

…adoc Co-authored-by: Maximilian Kolb <[email protected]>

adamruzicka reviewed Sep 3, 2024

View reviewed changes

maximiliankolb reviewed Sep 4, 2024

View reviewed changes

maximiliankolb reviewed Sep 5, 2024

View reviewed changes

Lennonka and others added 7 commits September 5, 2024 22:49

Apply suggestions from review

0c94fed

Co-authored-by: Maximilian Kolb <[email protected]>

Use example FQDN instead of hostname command

363cd61

Reformat JSON data options

134953c

Remove duplicate explanation

8771f88

Improve intro

6c39251

Reword a line

b7ac777

Replace SAT stuff

73e3031

Add the bytes unit

f09008c

maximiliankolb approved these changes Sep 6, 2024

View reviewed changes

guides/common/modules/proc_uploading-content-to-projectserver.adoc Outdated Show resolved Hide resolved

guides/common/modules/proc_calling-the-api-in-curl.adoc Outdated Show resolved Hide resolved

Apply suggestions from review

1cf4cf8

Lennonka merged commit d7fbafe into theforeman:master Sep 6, 2024
8 of 9 checks passed

Lennonka deleted the upstreamize-api-guide branch September 6, 2024 09:06

Lennonka added a commit that referenced this pull request Sep 6, 2024

Upstreamize API guide (#3212)

cd7b2a1

Co-authored-by: Maximilian Kolb <[email protected]>

aneta-petrova mentioned this pull request Nov 14, 2024

Include Hammer and API guides for all builds #3455

Merged

7 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Upstreamize API guide #3212

Upstreamize API guide #3212

Lennonka commented Aug 12, 2024 •

edited

Loading

github-actions bot commented Aug 12, 2024 •

edited

Loading

This comment was marked as outdated.

Lennonka commented Aug 19, 2024

Lennonka commented Aug 27, 2024

Lennonka commented Aug 27, 2024

maximiliankolb left a comment

maximiliankolb left a comment

maximiliankolb Aug 27, 2024

aneta-petrova Aug 27, 2024

Lennonka commented Aug 28, 2024 •

edited

Loading

Lennonka commented Sep 2, 2024

maximiliankolb left a comment

maximiliankolb Sep 3, 2024

Lennonka Sep 3, 2024

Lennonka Sep 5, 2024

Lennonka Sep 3, 2024

Lennonka commented Sep 3, 2024

adamruzicka Sep 3, 2024

maximiliankolb left a comment

maximiliankolb left a comment

maximiliankolb Sep 5, 2024

Lennonka commented Sep 5, 2024

maximiliankolb left a comment

Lennonka commented Sep 6, 2024

Lennonka commented Sep 6, 2024

maximiliankolb commented Sep 6, 2024

	[id="ex-API_Guide-Creating_a_New_User"]
	[id="creating-a-user"]

	They fetch and cache the API definition from {Project} and then generate API calls on demand.
	They fetch and cache the API definition from {Project} and then generate API calls on-demand.

Upstreamize API guide #3212

Upstreamize API guide #3212

Conversation

Lennonka commented Aug 12, 2024 • edited Loading

github-actions bot commented Aug 12, 2024 • edited Loading

This comment was marked as outdated.

Lennonka commented Aug 19, 2024

Lennonka commented Aug 27, 2024

Lennonka commented Aug 27, 2024

maximiliankolb left a comment

Choose a reason for hiding this comment

maximiliankolb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Lennonka commented Aug 28, 2024 • edited Loading

Re. API permission matrix

Lennonka commented Sep 2, 2024

maximiliankolb 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

Lennonka commented Sep 3, 2024

Choose a reason for hiding this comment

maximiliankolb left a comment

Choose a reason for hiding this comment

maximiliankolb left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Lennonka commented Sep 5, 2024

maximiliankolb left a comment

Choose a reason for hiding this comment

Lennonka commented Sep 6, 2024

Lennonka commented Sep 6, 2024

maximiliankolb commented Sep 6, 2024

Lennonka commented Aug 12, 2024 •

edited

Loading

github-actions bot commented Aug 12, 2024 •

edited

Loading

Lennonka commented Aug 28, 2024 •

edited

Loading